Prompt Workflow Documentation

This documentation describes the prompt workflow used in this repository, structured according to the Diátaxis Framework. It explains how to author specifications, derive implementation plans, decompose work, implement tasks, and manage architecture decisions—while ensuring traceability and consistency.

Overview

  • Diátaxis structure: Tutorials, How-to Guides, Reference, Explanations
  • Prompt suite (primary):
    • author-specification
    • derive-implementation-plan
    • decompose-feature-work
    • implement-next-work-item
    • author-adr
    • propagate-adr
    • author-refactor-plan
  • ID system: FR-, NFR-, API-, SEC-, DEP-, DECISION-, AC-, ASM-, TASK-, TEST-, RISK-, COMP-, OBS-, OPS-, DOC-, DOC-WI-
  • Greenfield presets: .github/presets/*.yaml (suggestion-only; ignored after spec exists)

New/Updated Rules

  • Propagation requires ADR references: all files updated by propagate-adr must include adr_refs in front matter (if present) and a Change History entry noting ADR-NNNN and path.
  • ADR authoring uses coded bullets: CTR-/DEC-/POS-/NEG-/ALT-/IMP-/CHG-/REF- (see Reference: ADR Codes Legend).

Canonical standards and guardrails

  • Canonical rules: See .github/instructions/prompt-standards.md (source of truth)
  • Interaction: All interactive prompts follow a single-question loop with a Context Snapshot and a Confirmation Gate
  • Code edits: Only implement-next-work-item may modify source code; all others update docs/plans/ADRs
  • Status: Use exact Shields.io tokens (brightgreen, yellow, blue, red, orange) and follow status transitions in standards §4.1

End-to-end Flow

flowchart TD
  A[Author Specification] -->|docs/specification.md| B[Derive Implementation Plan]
  B --> C[Decompose Feature Work]
  C --> D[Implement Next Work Item]
  D --> E{Need Spec Change?}
  E -- yes --> F[Author ADR]
  F --> G[Propagate ADR]
  G -->|updates| A
  E -- no --> H[Done]
  • Existing project mode: the prompts analyze the codebase first and extend current patterns rather than replace them.
  • Greenfield mode: prompts may suggest org presets during discovery; once confirmed, the spec becomes the only source of truth.

Where to start

  • New system: start with Tutorials (greenfield or existing-project)
  • Then follow How-to guides for specific actions (presets, ADRs, implementing a WI)
  • Consult Reference for schemas, IDs, and prompt contracts
  • Read Explanations for design rationale and governance