feat(story-6.1): implement architect and readiness validator structural context
The bmad-create-architecture and bmad-check-implementation-readiness workflows now integrate Memtrace structural graph queries. The architect queries get_codebase_briefing, list_communities, find_central_symbols, find_bridge_symbols during Step 2 (context) and validates proposed architecture against graph communities in Step 7 (validation). The readiness validator cross-references PRD claims against the actual codebase in Step 2 and reports structural readiness in Step 6. FR11: Architect Agent queries structural dependencies during design FR19: Readiness Validator cross-references PRD proposals against graph
This commit is contained in:
Magal
parent
afde2efcf6
commit
ea813716e2
|
|
@ -37,6 +37,7 @@ activation_steps_append = []
|
|||
|
||||
persistent_facts = [
|
||||
"file:{project-root}/**/project-context.md",
|
||||
"Memtrace graph queries are available for structural dependency discovery during architecture design. Use the adapter at _bmad/scripts/memtrace/memtrace-adapter.mjs with --query get_impact --check-freshness --summarize for blast radius analysis, or use direct MCP tools (get_codebase_briefing, list_communities, find_dependency_path, find_central_symbols, find_bridge_symbols, find_api_endpoints, get_impact) for structural exploration. All queries MUST use sequential for...of with await — NEVER Promise.all. Prefer summarized output to stay under 2000 token limit.",
|
||||
]
|
||||
|
||||
role = "Convert the PRD and UX into technical architecture decisions that keep implementation on track during the BMad Method solutioning phase."
|
||||
|
|
|
|||
|
|
@ -115,6 +115,64 @@ Look for:
|
|||
- Business constraints
|
||||
- Integration requirements
|
||||
|
||||
### 5.5: Structural Assumptions Verification (Memtrace)
|
||||
|
||||
If the repository is indexed by Memtrace, verify architectural claims in the PRD against the actual codebase graph. This step is ADVISORY.
|
||||
|
||||
**Check Availability:**
|
||||
- Call `list_indexed_repositories` (Memtrace MCP tool, direct call) to confirm the project repo is indexed
|
||||
- Check the `last_indexed_at` value — if older than 30 minutes, flag as stale and skip graph queries
|
||||
- If not indexed, skip and note "Structural verification unavailable"
|
||||
|
||||
**Verify PRD Claims:**
|
||||
|
||||
Scan the PRD for architectural claims (dependency relationships, centrality assertions, module boundaries, or scope claims). If the PRD contains no explicit architectural claims, note "No structural claims to verify" and skip this section.
|
||||
|
||||
For each architectural claim found (e.g., "module X depends on module Y", "component Z is central to the system"), verify against the graph:
|
||||
|
||||
1. **Dependency Claims:** For each stated dependency between modules/components, resolve module names to symbols by searching for key exports, classes, or entry points within each module. Then use `find_dependency_path` (Memtrace MCP tool, direct call) with the resolved source and target symbols to confirm the actual path exists. Flag claims where no path exists or the direction is reversed.
|
||||
|
||||
2. **Centrality Claims:** For modules/components described as "core" or "central", use `find_central_symbols` (Memtrace MCP tool, direct call) to verify their actual PageRank position.
|
||||
|
||||
3. **Module Boundary Claims:** If the PRD describes module/component boundaries, compare against `list_communities` to verify those boundaries align with the actual graph communities.
|
||||
|
||||
4. **Scope Claims:** If the PRD claims specific scope (e.g., "this change affects only module X"), use `get_impact` on the target symbols to verify the actual blast radius. If the PRD doesn't name specific symbols, note "Cannot verify scope claims — no target symbols specified in PRD" as a warning rather than attempting arbitrary queries.
|
||||
|
||||
**Document Findings:**
|
||||
|
||||
Include in the PRD Analysis section under "PRD Structural Verification":
|
||||
|
||||
```markdown
|
||||
### PRD Structural Verification {✅/⚠️/—}
|
||||
|
||||
{If verified — all claims confirmed:}
|
||||
✅ **PRD claims verified against codebase graph:**
|
||||
- {count} dependency claims confirmed out of {total} verified
|
||||
- Centrality claims match actual graph structure
|
||||
- Module boundaries align with graph communities
|
||||
|
||||
{If mismatches found — some claims contradicted:}
|
||||
⚠️ **PRD claims contradicted by codebase graph ({contradicted_count} of {total}):**
|
||||
- {claim 1} — Actual graph shows {reality}
|
||||
- {claim 2} — Actual graph shows {reality}
|
||||
- Flag these mismatches for human review — the agent cannot determine whether the PRD or the graph is correct.
|
||||
|
||||
{If no claims found in PRD:}
|
||||
— No architectural claims found in PRD to verify against codebase graph.
|
||||
|
||||
{If no target symbols for scope claims:}
|
||||
— Cannot verify scope claims — no target symbols specified in PRD.
|
||||
|
||||
{If unavailable (no indexed repo or stale index):}
|
||||
— Structural verification unavailable — no indexed repository found (or index is stale).
|
||||
PRD claims could not be verified against actual codebase structure.
|
||||
```
|
||||
|
||||
**Graceful Degradation:**
|
||||
- Memtrace unavailability does NOT block the step — proceed with document-based analysis
|
||||
- Structural mismatches are WARNINGS, not errors — flag for human review
|
||||
- PRDs with no architectural claims skip cleanly with a note
|
||||
|
||||
### 6. Add to Assessment Report
|
||||
|
||||
Append to {outputFile}:
|
||||
|
|
@ -134,6 +192,10 @@ Append to {outputFile}:
|
|||
|
||||
[Any other requirements or constraints found]
|
||||
|
||||
### PRD Structural Verification
|
||||
|
||||
[Findings from section 5.5]
|
||||
|
||||
### PRD Completeness Assessment
|
||||
|
||||
[Initial assessment of PRD completeness and clarity]
|
||||
|
|
@ -156,6 +218,7 @@ PRD analysis complete. Read fully and follow: `./step-03-epic-coverage-validatio
|
|||
- PRD loaded and read completely
|
||||
- All FRs extracted with full text
|
||||
- All NFRs identified and documented
|
||||
- PRD structural assumptions verified against codebase graph (if repository indexed)
|
||||
- Findings added to assessment report
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
|
|
|
|||
|
|
@ -59,6 +59,7 @@ Check the {outputFile} for sections added by previous steps:
|
|||
- File and FR Validation findings
|
||||
- UX Alignment issues
|
||||
- Epic Quality violations
|
||||
- PRD Structural Verification findings (from Step 2)
|
||||
|
||||
### 3. Add Final Assessment Section
|
||||
|
||||
|
|
@ -70,6 +71,7 @@ Append to {outputFile}:
|
|||
### Overall Readiness Status
|
||||
|
||||
[READY/NEEDS WORK/NOT READY]
|
||||
**Structural Verification:** {Available and consistent / Available with warnings / Partial / Unavailable}
|
||||
|
||||
### Critical Issues Requiring Immediate Action
|
||||
|
||||
|
|
@ -80,6 +82,8 @@ Append to {outputFile}:
|
|||
1. [Specific action item 1]
|
||||
2. [Specific action item 2]
|
||||
3. [Specific action item 3]
|
||||
{If structural warnings exist:}
|
||||
- Review PRD assumptions flagged by structural verification — {contradicted_count} of {total} PRD claims contradicted by actual codebase graph (see PRD Structural Verification section)
|
||||
|
||||
### Final Note
|
||||
|
||||
|
|
|
|||
|
|
@ -77,6 +77,56 @@ Fully read and Analyze the loaded project documents to understand architectural
|
|||
- Offline capability requirements
|
||||
- Performance expectations (load times, interaction responsiveness)
|
||||
|
||||
### 1.5: Gather Structural Context (Memtrace)
|
||||
|
||||
If the project repository is indexed by Memtrace, query the graph to ground the architecture in actual codebase structure. This step is ADVISORY — skip if Memtrace is unavailable.
|
||||
|
||||
**Check Availability:**
|
||||
- Call `list_indexed_repositories` (Memtrace MCP tool — callable directly through the agent's tool interface, no adapter needed for this lightweight query)
|
||||
- Check the `last_indexed_at` value in the response: if older than 30 minutes, note that the index may be stale and skip graph queries
|
||||
- If no indexed repo matches the project root, skip this sub-section and note "Structural context unavailable — no indexed repository found" in the analysis
|
||||
|
||||
**If Available — Query Structural Facts:**
|
||||
|
||||
1. **Get Codebase Briefing:** Call `get_codebase_briefing` (Memtrace MCP tool, direct call) to understand scale, module count, endpoint coverage, and high-risk symbols. Map response fields to the template as follows: `briefing.total_symbols` → `{node_count}`, `briefing.community_count` → `{community_count}`.
|
||||
|
||||
2. **Discover Module Boundaries:** Call `list_communities` (Memtrace MCP tool, direct call) to identify actual logical modules (community clusters). These represent real bounded contexts that may differ from the directory structure.
|
||||
|
||||
3. **For Brownfield Projects — Map Existing Architecture:**
|
||||
- Call `find_central_symbols` (limit 10) to identify load-bearing code
|
||||
- Call `find_bridge_symbols` (limit 10) to find architectural chokepoints
|
||||
- If the PRD mentions specific modules or components, use `find_dependency_path` to verify actual relationships
|
||||
|
||||
**Document Findings:**
|
||||
|
||||
Include in the "Project Context Analysis" section under a new "Existing Codebase Structure" subsection:
|
||||
|
||||
```markdown
|
||||
### Existing Codebase Structure (Memtrace)
|
||||
|
||||
{If available and all queries succeeded:}
|
||||
- **Repository scale:** {node_count} symbols across {community_count} logical modules
|
||||
- **Central symbols (highest PageRank):** {list of top symbols}
|
||||
- **Bridge/chokepoint symbols:** {list of bridge symbols}
|
||||
- **Community clusters:** {summary of major communities and their sizes}
|
||||
- **Brownfield integration points:** {key modules the new work must integrate with}
|
||||
|
||||
{If partial: some queries succeeded, some failed:}
|
||||
- **Partial structural context (some queries failed):** {what was successfully retrieved}
|
||||
- **Failed queries:** {list of queries that failed}
|
||||
- Structural context is incomplete — note which aspects could not be determined.
|
||||
|
||||
{If unavailable (no indexed repo or index is stale):}
|
||||
- Structural context unavailable — no indexed repository found (or index is stale). Architectural decisions will be based on documented requirements only.
|
||||
```
|
||||
|
||||
**Graceful Degradation:**
|
||||
- If `list_indexed_repositories` returns empty or the project repo is not indexed: skip
|
||||
- If the repository is indexed but no communities are found (greenfield project): skip community-level queries, note "Empty graph — project has no existing codebase structure to analyze"
|
||||
- If some queries succeed and others fail: document partial results (see "Partial" template above)
|
||||
- If all queries time out or fail: note the failure and skip remaining queries
|
||||
- NEVER block the workflow on Memtrace availability — this is advisory context
|
||||
|
||||
### 2. Project Scale Assessment
|
||||
|
||||
Calculate and present project complexity:
|
||||
|
|
@ -203,6 +253,7 @@ When user selects 'C', append the content directly to the document using the str
|
|||
✅ User confirmation of project understanding
|
||||
✅ A/P/C menu presented and handled correctly
|
||||
✅ Content properly appended to document when C selected
|
||||
✅ Structural context gathered from Memtrace graph (if repository is indexed)
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
|
|
@ -212,6 +263,7 @@ When user selects 'C', append the content directly to the document using the str
|
|||
❌ Underestimating complexity indicators
|
||||
❌ Generating content without real analysis of loaded documents
|
||||
❌ Not presenting A/P/C menu after content generation
|
||||
❌ Failing to gracefully skip Memtrace queries when repository is not indexed
|
||||
|
||||
❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
|
||||
❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
|
||||
|
|
|
|||
|
|
@ -125,6 +125,68 @@ Assess if AI agents can implement consistently:
|
|||
- Are communication patterns fully specified?
|
||||
- Are process patterns (error handling, etc.) complete?
|
||||
|
||||
### 3.5: Structural Coherence Validation (Memtrace)
|
||||
|
||||
If the project has an indexed repository, validate that the proposed architecture aligns with the actual codebase graph. This step is ADVISORY.
|
||||
|
||||
**Check Availability:**
|
||||
- Call `list_indexed_repositories` (Memtrace MCP tool, direct call) to confirm the project repo is indexed
|
||||
- Check the `last_indexed_at` value — if older than 30 minutes, flag as stale and skip graph queries
|
||||
- If not indexed, skip and note "Structural coherence validation unavailable"
|
||||
- If the project is greenfield (no existing codebase), skip structural validation — `list_communities` will return empty and all dependency checks would produce false positives
|
||||
|
||||
**Validate Proposed Structure Against Graph:**
|
||||
|
||||
1. **Module Boundary Verification:**
|
||||
- Compare the proposed directory structure (from Step 6) against `list_communities` output
|
||||
- A "match" is when the majority of symbols in a proposed directory belong to a single graph community (heuristic: >50% of directory's symbols share the same community ID)
|
||||
- Flag any proposed module that splits a natural graph community across directories
|
||||
- Flag any proposed module that merges two distinct graph communities
|
||||
|
||||
2. **Dependency Direction Check:**
|
||||
- For each proposed integration point or dependency in the architecture, use `find_dependency_path` to verify the actual call direction. Resolve module names to symbols by searching for key exports, classes, or entry points within each module.
|
||||
- Flag reversed dependencies (architecture says A→B but graph shows B→A)
|
||||
- Flag missing dependencies (architecture says A→B but no path exists in graph)
|
||||
|
||||
3. **Brownfield Conflict Detection:**
|
||||
- Check proposed new modules against `find_central_symbols` — flag if a proposed module would duplicate or conflict with existing central code
|
||||
- Check proposed new API patterns against `find_api_endpoints` — flag if the proposed API surface overlaps with existing endpoints. "Overlap" means: same HTTP method + same URL path template. Flag for human review if overlap is detected.
|
||||
|
||||
**Document in Validation Results:**
|
||||
|
||||
Add to the "Architecture Validation Results" section under "Structural Coherence Validation":
|
||||
|
||||
```markdown
|
||||
### Structural Coherence Validation {✅/⚠️/—}
|
||||
|
||||
{If available and all checks pass:}
|
||||
✅ **Structural Coherence: CONFIRMED**
|
||||
- Proposed module boundaries match {match_count}/{total_count} graph communities
|
||||
- All {dep_count} proposed dependency directions verified against actual call graph
|
||||
- No conflicts detected between proposed and existing architecture
|
||||
|
||||
{If available with warnings:}
|
||||
⚠️ **Structural Coherence: WARNINGS**
|
||||
- {warning_summary}
|
||||
- See Gap Analysis for details
|
||||
|
||||
{If partial checks (some queries failed):}
|
||||
⚠️ **Structural Coherence: PARTIAL**
|
||||
- {What was verified successfully}
|
||||
- {What could not be verified due to query failures}
|
||||
- See Gap Analysis for details
|
||||
|
||||
{If unavailable (no indexed repo, stale index, or greenfield):}
|
||||
— Structural coherence validation unavailable — no indexed repository found (or project is greenfield).
|
||||
Architecture coherence is assessed on documentation alone.
|
||||
```
|
||||
|
||||
**Graceful Degradation:**
|
||||
- Memtrace unavailability does NOT affect the overall readiness assessment
|
||||
- Warnings from structural validation appear in Gap Analysis as "Important Gaps"
|
||||
- Partial results are still useful — document what succeeded and what failed
|
||||
- NEVER downgrade the architecture readiness status solely due to structural validation unavailability
|
||||
|
||||
### 4. Gap Analysis
|
||||
|
||||
Identify and document any missing elements:
|
||||
|
|
@ -257,9 +319,15 @@ Mark each item `[x]` only if validation confirms it; leave `[ ]` if it is missin
|
|||
- [ ] Integration points mapped
|
||||
- [ ] Requirements to structure mapping complete
|
||||
|
||||
**Structural Validation (advisory — does not block READY FOR IMPLEMENTATION)**
|
||||
|
||||
- [ ] Module boundaries verified against graph communities
|
||||
- [ ] Dependency directions confirmed against call graph
|
||||
- [ ] Brownfield conflicts checked (if applicable)
|
||||
|
||||
### Architecture Readiness Assessment
|
||||
|
||||
**Overall Status:** {{READY FOR IMPLEMENTATION | READY WITH MINOR GAPS | NOT READY}} (choose READY FOR IMPLEMENTATION only when all 16 checklist items are `[x]` and no Critical Gaps remain; choose NOT READY when any Critical Gap is open or any Requirements Analysis or Architectural Decisions item is unchecked; otherwise READY WITH MINOR GAPS)
|
||||
**Overall Status:** {{READY FOR IMPLEMENTATION | READY WITH MINOR GAPS | NOT READY}} (choose READY FOR IMPLEMENTATION only when all 16 standard checklist items are `[x]` (Structural Validation items are advisory) and no Critical Gaps remain; choose NOT READY when any Critical Gap is open or any Requirements Analysis or Architectural Decisions item is unchecked; otherwise READY WITH MINOR GAPS. Structural Validation items are advisory — unchecked structural items do NOT block READY FOR IMPLEMENTATION.)
|
||||
|
||||
**Confidence Level:** {{high/medium/low}} based on validation results
|
||||
|
||||
|
|
@ -338,6 +406,7 @@ When user selects 'C', append the content directly to the document using the str
|
|||
✅ Implementation readiness confirmed
|
||||
✅ All gaps identified and addressed
|
||||
✅ Comprehensive validation checklist completed
|
||||
✅ Structural coherence validated against real codebase graph (if repository indexed)
|
||||
✅ A/P/C menu presented and handled correctly
|
||||
✅ Content properly appended to document when C selected
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue