pal-e-docs

TODO: Refine Issue Template for Issue-as-Spec Pattern

todo-issue-as-spec-pattern Todo

todo done
Project

TODO: Refine Issue Template for Issue-as-Spec Pattern

Status: DONE (2026-03-02)

Problem

Agent spawn prompts were 3-4KB because we didn't trust issues to be complete specs. We duplicated plan context, file targets, and acceptance criteria in the prompt instead of pointing agents at the issue.

What We Did

  • [x] Revised template-issue — issues live in Forgejo (Markdown), not pal-e-docs (HTML). Added File Targets, Context, Test Expectations, Constraints.
  • [x] Revised template-plan — phases link directly to Forgejo issues. No pal-e-docs issue notes.
  • [x] Revised agent-spawn-conventions — minimal prompt pattern (~100 tokens), agents read Forgejo issues only, no pal-e-docs access.
  • [x] Updated check-agent-spawn.sh — accepts todo- slugs.
  • [x] Updated check-issue-template.sh — reads only first pre block (Forgejo template, not tracker template).
  • [x] Dogfooded on pal-e-docs-mcp Forgejo #7 — agent executed from Forgejo issue alone, ~100 token prompt, 31K total tokens, 2.7 min.
  • [x] Eliminated pal-e-docs issue notes entirely — the biggest simplification. Issues = Forgejo issues. pal-e-docs tracks projects, plans, phases, SOPs. Forgejo tracks issues, PRs, code.

Key Decisions

  • Agent access: issue-only. Dev agents read Forgejo issue + repo codebase. No pal-e-docs access.
  • Betty Sue / agent boundary = pal-e-docs / Forgejo boundary. HTML for planning, Markdown for execution.
  • No pal-e-docs issue notes. The Forgejo issue IS the spec. The plan phase IS the tracker.
  • template-issue — the Forgejo issue template
  • template-plan — phases link to Forgejo issues
  • agent-spawn-conventions — minimal prompt pattern