Grace-marketplace 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

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)