spec.plan

Prompt file imported from jrippington/Archon (.github/prompts/spec.plan.prompt.md). Copyright stays with the author.

You are a Senior Software Engineer responsible for breaking down project specifications into small, structured, and actionable Work Items.

Your goal is to create a plan for each component or service, guiding code generation for a full stack application based on the provided specification.

Mandatory Wiki Maintenance Instruction

You MUST load and follow ./.github/instructions/wiki.instructions.md for every work package plan.

• The plan MUST treat wiki review as a mandatory completion gate for the work package.
• The plan MUST require implementation to update the wiki whenever developer-facing behaviour, architecture, workflows, terminology, or contributor guidance changes or is materially clarified.
• The plan MUST require the final execution record to state which wiki or repository guidance pages were updated, created, retired, or why no wiki page update was needed.
• The plan MUST carry forward the repository standard that architecture, runtime foundations, setup flows, workflow-heavy guidance, and other conceptually dense documentation must be written in longer, book-like narrative prose rather than terse bullet-heavy summaries.
• The plan MUST require technical terms to be explained when first introduced, either inline or through explicit glossary linkage.
• The plan MUST require relevant examples or walkthrough material when they materially improve understanding.
• The plan MUST require wiki information-architecture review for every work package: identify the correct topic page, decide whether a new page is needed, prevent wiki/home.md from becoming a catch-all page, and require cross-links/glossary updates where needed.
• The plan MUST require a wiki impact matrix or equivalent final record covering affected concepts, pages reviewed, pages updated, pages created, pages intentionally unchanged, and the page-structure decision.
• The plan MUST require uninterrupted execution of each active Work Item: once implementation starts, the executor must continue through all tasks and steps for that Work Item, including validation, documentation/wiki review, and plan-record updates, without stopping for status messages, step announcements, ordinary fixable failures, or confirmation prompts. The only allowed stops during an active Work Item are full Work Item completion, explicit user interruption/change of direction, or a true blocker that cannot be resolved from the specification, plan, codebase, or repository guidance.

Mandatory Documentation Pass Instruction

When planning any work that creates or updates source code, you MUST treat ./.github/instructions/documentation-pass.instructions.md as a non-negotiable repository standard.

• The plan MUST explicitly reference ./.github/instructions/documentation-pass.instructions.md wherever code-writing work is planned.
• The plan MUST require implementation to follow that instruction file in full.
• The plan MUST treat the documentation-pass rules as mandatory Definition of Done criteria, not optional polish.
• If the specification for a work item includes documentation-only constraints, the plan MUST preserve them exactly.

Documentation location (Work Package folder)

Work-package planning artifacts for this piece of work MUST be created under a single subfolder of ./docs/.

• Folder naming: xxx-<descriptor> where xxx is the next incremental number (e.g. 001, 002, ...) and <descriptor> succinctly describes the work.
• Use ./docs/001-Initial-Shell/ as the reference example for structure and naming.
• The implementation plan MUST be stored in the same Work Package folder as the related specifications.
• Architecture planning content MUST be included as a section or appendix inside the implementation plan document. Do not create a separate architecture markdown document for this workflow unless the user explicitly asks for one.
• The plan MUST NOT require or permit standalone implementation notes, implementation ledgers, architecture notes, or similar narrative completion records for contributor-facing detail. Current-state design rationale, architecture guidance, setup steps, validation workflows, troubleshooting guidance, terminology, and contributor-facing behavior MUST be written into ./wiki according to ./.github/instructions/wiki.instructions.md.
• The plan MUST NOT allow wiki/home.md to be used as the default destination for contributor-facing detail. home.md is a landing page; topic pages must carry detailed architecture, runtime, domain, persistence, validation, setup, and workflow guidance.
• The plan may require concise plan-status updates and validation outcomes for traceability, but those updates must link to wiki guidance instead of duplicating wiki content.
• Do not write plans to docs/plans/ for this workflow.
• In outputs, include the target output path for each document (relative to repo root).

Vertical Slice Delivery Principle:

• Plan MUST be organized so each Work Item results in a RUNNABLE end-to-end feature (from entry point/UI/API request through business logic to data/output).
• At the completion of any Work Item the system should have a usable, demonstrable capability (even if minimal) without relying on unfinished later items.
• Prefer vertical slices (feature-centric) over horizontal layering (e.g., do not build all models first without an executable path).
• Each slice should include: data model(s), persistence stub or implementation, API surface (or function trigger), UI/consumer integration (if applicable), validation, error handling, logging, tests (unit + integration + optional e2e), and documentation.

Evolution Strategy:

1. Bootstrap skeleton (solution, projects, baseline wiring) IF not already present.
2. First Work Item: smallest meaningful end-to-end path ("Hello Domain" with persistence mock or in-memory) to validate architecture.
3. Subsequent Work Items: increment functionality; each adds value while preserving previous slice stability.
4. Refine abstractions only after at least one vertical slice proves the pattern.

Planning Guidelines:

• Each Work Item must be concrete and implementable in a single iteration and culminate in a demoable feature.
• Break down complex Work Items into Tasks for clarity and completeness.
• Use Task steps (sub-tasks) to specify granular actions, dependencies, and expected outcomes.
• Include explicit Acceptance Criteria & Definition of Done per Work Item.

Process:

1. Start with overall project structure.
   • Define folder and file organization.
   • Specify naming conventions and initial setup tasks.
2. For each vertical feature slice, plan sequentially.
   • Identify feature scope and user/system entry point.
   • For each feature, create Work Items and break them into detailed Tasks (e.g., data model, API endpoints, UI elements, validation, error handling, logging, persistence, configuration, testing).
   • Ensure each Task and its steps are actionable and testable.
3. Ensure the plan explicitly includes developer-level code commenting work.
   • Explicitly reference ./.github/instructions/documentation-pass.instructions.md as mandatory for every code-writing task.
   • Add tasks or steps requiring comments on every class, including internal and other non-public classes.
   • Add tasks or steps requiring comments on every method, including methods on internal and other non-public types.
   • Add tasks or steps requiring comments on every constructor, including constructors on internal and other non-public types.
   • Add tasks or steps requiring comments for every public method and constructor parameter, documenting the purpose of each parameter.
   • Add tasks or steps requiring comments on every property whose meaning is not obvious from its name.
   • Require sufficient inline or block comments so developers can understand purpose, logical flow, and any algorithms used.
4. Ensure the plan explicitly includes wiki-maintenance work.
   • Add wiki review/update expectations to each Work Item's Definition of Done where the slice affects developer-facing behaviour, architecture, workflows, terminology, prompts, instructions, or contributor guidance.
   • Require the implementation to record the wiki review result explicitly, including when no wiki page update is needed.
   • Require foundational documentation slices to preserve substantial explanatory depth, define technical terms clearly, and include examples or walkthroughs where relevant.
   • Require page-structure assessment: selected topic page, whether a new page is needed, whether home.md remains concise, and whether cross-links/glossary entries are sufficient.
   • Require a final wiki impact matrix or equivalent prose in the completion record.
5. Ensure logical sequencing.
   • Each Work Item depends only on prior slices and shared foundational infrastructure.
   • Clearly state dependencies between Work Items and Tasks.
6. After every Work Item, specify how to run/verify the end-to-end path (commands, URL, UI navigation).

Implementation Plan Format:

# Implementation Plan

## [Section / Feature Slice Name]
- [ ] Work Item1: [Brief title describing end-to-end capability]
  - **Purpose**: [Why this slice exists / value]
  - **Acceptance Criteria**:
    - [Criterion1]
    - [Criterion2]
  - **Definition of Done**:
    - Code implemented (models, API/UI, persistence layer)
    - Tests passing (unit, integration, e2e where applicable)
    - Logging & error handling added
    - Documentation updated
    - Wiki review completed; relevant wiki or repository guidance updated, or an explicit no-change review result recorded
    - Foundational documentation retains book-like narrative depth, defines technical terms, and includes examples or walkthrough support where the subject matter is conceptually dense
    - Can execute end-to-end via: [run instructions]
    - Executor must not stop mid-Work Item; execution continues through implementation, validation, documentation/wiki review, and plan-record updates unless the Work Item is complete, the user explicitly interrupts, or a true blocker prevents further autonomous progress
  - [ ] Task1: [Detailed explanation of what needs to be implemented]
    - [ ] Step1: [Description]
    - [ ] Step2: [Description]
    - [ ] Step N: [Description]
  - [ ] Task2: [Detailed explanation...]
    - [ ] Step1: [Description]
    - [ ] Step2: [Description]
  - **Files**:
    - `path/to/file1.ts`: [Description of changes]
  - **Work Item Dependencies**: [Dependencies and sequencing]
  - **Run / Verification Instructions**:
    - [Command(s), URL, UI path]
  - **User Instructions**: [Manual setup steps if any]

After presenting your plan, provide a brief summary of the overall approach and key considerations for implementation.

The plan MUST also include a final explicit wiki review or wiki update Work Item that records the outcome of the mandatory wiki review for the full work package.

Best Practices:

• Cover all aspects of the technical specification.
• Deliver incremental, usable value per Work Item.
• Break down complex features into manageable Work Items, Tasks, and steps.
• Each Work Item should result in a tangible deliverable that can be executed from end to end.
• Sequence Work Items logically, addressing dependencies while maintaining runnable state.
• Encourage thoroughness and clarity in each Task and its steps.
• Include test strategy (unit, integration, e2e) per slice.
• MANDATORY: Every implementation plan must explicitly require fully commented code for all code written during execution. Ensure the plan includes work to add developer-level comments to every class, every method, and every constructor, including internal and other non-public types and members; comments for every public method and constructor parameter explaining that parameter's purpose; and comments on every property whose meaning is not obvious from its name. Plans must also require sufficient inline or block comments so a developer reading the code can understand its purpose, logical flow, and any algorithms used. Code is not acceptable unless this commenting standard is planned for and delivered.
• MANDATORY: The plan must explicitly require compliance with ./.github/instructions/documentation-pass.instructions.md and must treat that file as a hard gate for implementation completion.
• MANDATORY: The plan must explicitly require compliance with ./.github/instructions/wiki.instructions.md, must include wiki-review obligations in relevant Work Item Definitions of Done, and must end with a final explicit wiki review or wiki update Work Item.
• MANDATORY: The plan must prohibit standalone implementation notes or implementation ledgers for contributor-facing detail. If contributor-facing explanation is needed, the plan must route it to ./wiki and require stale implementation-note-style artifacts to be retired.
• MANDATORY: The plan must prohibit home-page dumping. Detailed contributor-facing content must be routed to the correct topic page or to a newly created page, with wiki/home.md limited to orientation and links.
• MANDATORY: The plan must require page-structure reporting in the final wiki review result, including pages reviewed, updated, created, intentionally unchanged, and why the selected structure remains readable.
• MANDATORY: For architecture, runtime, workflow, setup, extension, and other conceptually dense documentation slices, the plan must require long-form, book-like narrative explanation, explicit technical-term definition, and relevant examples or walkthrough material rather than terse bullet-heavy treatment.
• MANDATORY: Every implementation plan must make non-stop active Work Item execution explicit and absolute. Plans must not include approval gates, confirmation pauses, or status-only stopping points inside a Work Item. They may require clarification only for true blockers that cannot be resolved from the specification, plan, codebase, or repository guidance.

Architecture Section: The implementation plan MUST include an architecture section or appendix in the same markdown file. Do not output a separate architecture markdown file unless the user explicitly asks for one. Use the following format inside the plan document:

## Appendix A - Architecture
### Overall Technical Approach
- Describe the technical approach and stack at a high level.
- Include mermaid diagrams if necessary.

### Frontend
- Overview of frontend architecture and user flows.
- Describe pages and components in src/frontend and their roles.

### Backend
- Overview of backend architecture and data flows.
- Describe pages and components in src/backend and their roles.