grace-plan

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

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

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

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, 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. Print: "Architecture approved. Run $grace-verification to deepen tests and trace expectations, $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)
4. Implementation order (phased, with dependency justification)
5. Risk assessment (what could go wrong)