Grace Plan

---
name: grace-plan
description: "Run the GRACE architectural planning phase. Use when you have requirements and technology decisions defined and need to design the module architecture, create contracts, map data flows, and establish verification references. Produces development-plan.xml, verification-plan.xml, and knowledge-graph.xml."
---

Run the GRACE architectural planning phase.

## Prerequisites
- `docs/requirements.xml` must exist and have at least one UseCase
- `docs/technology.xml` must exist with stack decisions
- `docs/verification-plan.xml` should exist as the shared verification artifact template
- If requirements or technology are missing, tell the user to run `$grace-init` first
- If the verification plan template is missing, recreate it before finalizing the planning artifacts

## Architectural Principles

When designing the architecture, apply these principles:

### Contract-First Design
Every module gets a MODULE_CONTRACT before any code is written:
- PURPOSE: one sentence, what it does
- SCOPE: what operations are included
- DEPENDS: list of module dependencies
- LINKS: knowledge graph node references

### Module Taxonomy
Classify each module as one of:
- **ENTRY_POINT** — where execution begins (CLI, HTTP handler, event listener)
- **CORE_LOGIC** — business rules and domain logic
- **DATA_LAYER** — persistence, queries, caching
- **UI_COMPONENT** — user interface elements
- **UTILITY** — shared helpers, configuration, logging
- **INTEGRATION** — external service adapters

### Semantic Anchoring
Favor semantically rich module, function, flow, and block names.

- prefer names that carry domain meaning over abstract IDs or arbitrary placeholders
- make PURPOSE and SCOPE fields concrete enough that a worker can infer intent without guessing
- when a rule is subtle, include one or two compact examples in notes or verification scenarios instead of relying on a vague prose rule

### Reliability-First Stack Selection
Use `docs/technology.xml` to define an approved implementation stack for agents.

- name the preferred runtime libraries, test tools, logging stack, and framework surfaces explicitly
- note discouraged or non-default libraries when they would weaken autonomous reliability
- plan around tools and abstractions that the team is actually willing to verify and maintain

### Knowledge Graph Design
Structure `docs/knowledge-graph.xml` for maximum navigability:
- Each module gets a unique ID tag: `M-xxx NAME="..." TYPE="..."`
- Functions annotated as `fn-name`, types as `type-Name`
- CrossLinks connect dependent modules bidirectionally
- Annotations describe only the module's public interface
- Do not push private helpers or implementation-only types into shared XML artifacts

### Verification-Aware Planning
Planning is incomplete if modules cannot be verified.

For every significant module, define during planning:
- a `verification-ref` like `V-M-xxx`
- likely source and test file targets
- critical scenarios that must be checked
- the log or trace anchors needed to debug failures later
- which checks stay module-local versus wave-level or phase-level

## Process

### Phase 1: Analyze Requirements
Read `docs/requirements.xml`. For each UseCase, identify:
- What modules/components are needed
- What data flows between them
- What external services or APIs are involved

### Phase 2: Design Module Architecture
Propose a module breakdown. For each module, define:
- Purpose (one sentence)
- Type: ENTRY_POINT / CORE_LOGIC / DATA_LAYER / UI_COMPONENT / UTILITY / INTEGRATION
- Dependencies on other modules
- Key public interfaces (what the module exposes to other modules or callers)
- Tentative source path, test path, and `verification-ref`
- Semantic anchors the worker should reuse: module naming, function naming, and critical block names

Present this to the user as a structured list and **wait for approval** before proceeding.

### Phase 3: Design Verification Surfaces
Before finalizing the plan, derive the first verification draft:
- map critical UseCases to `DF-xxx` data flows
- assign `V-M-xxx` verification entries for important modules
- list the most important success and failure scenarios
- identify required log markers or trace evidence for critical branches
- note module-local checks plus any wave-level or phase-level follow-up
- define stop conditions or replan triggers for the highest-risk modules so execution can halt cleanly instead of drifting

Present this verification draft to the user as part of the same approval checkpoint. If the verification story is weak, revise the architecture before proceeding.

### Phase 4: Mental Walkthroughs
Run "mental tests" for 2-3 key user scenarios step by step:
- Which modules are involved?
- What data flows through them?
- Where could it break?
- Which logs or trace markers would prove the path was correct?
- Are there circular dependencies?

Present the walkthrough to the user. If issues are found — revise the architecture.

### Phase 5: Generate Artifacts
After user approval:

1. Update `docs/development-plan.xml` with the full module breakdown, public module contracts, target paths, observability notes, data flows, and implementation order. Use unique ID-based tags: `M-xxx` for modules, `Phase-N` for phases, `DF-xxx` for flows, `step-N` for steps, and `V-M-xxx` references for verification.
2. Update `docs/verification-plan.xml` with global verification policy, critical flows, module verification stubs, autonomy-gate evidence, and phase gates.
3. Update `docs/knowledge-graph.xml` with all modules (as `M-xxx` tags), their public-interface annotations (as `fn-name`, `type-Name`, etc.), `verification-ref` links, and CrossLinks between them.
4. Ensure `docs/technology.xml` explicitly names the preferred stack and observability surfaces the worker should stay inside.
5. Print: "Architecture approved. Run `$grace-verification` to deepen tests and trace expectations, `grace lint --profile autonomous` to check execution readiness, `$grace-execute` for sequential execution, or `$grace-multiagent-execute` for parallel-safe waves."

## Important
- Do NOT generate any code during this phase
- This phase produces ONLY planning documents and verification artifacts
- Every architectural decision must be explicitly approved by the user

## Output Format
Always produce:
1. Module breakdown table (ID, name, type, purpose, dependencies, target paths, verification ref)
2. Data flow diagrams (textual)
3. Verification surface overview (critical flows, module-local checks, log or trace anchors, stop conditions)
4. Implementation order (phased, with dependency justification)
5. Risk assessment (what could go wrong, and what should stop or replan execution)