Optimize map-efficient.md with 4 prompt engineering improvements#74
Optimize map-efficient.md with 4 prompt engineering improvements#74
Conversation
1. Semantic Brackets: Replace generic `**AI Packet (XML):**` markers with versioned `<MAP_Packet>`, `<MAP_Context>`, `<MAP_Contract>`, `<MAP_Written>` tags that give agents unambiguous context boundaries. 2. Protocol over Role: Replace vague "Follow Actor agent protocol" and generic "Check security, standards" with strict numbered protocol steps in both ACTOR and MONITOR prompts. Agents now execute a deterministic checklist rather than interpreting a role description. 3. Wenyan-style AAG contracts: DECOMPOSE phase now requires an `aag_contract` field per subtask (Actor -> Action -> Goal one-liner). Actor compiles this directly into code; Monitor verifies against it. Eliminates reasoning overhead (~30% token savings on Thinking). 4. Context Distillation: Step 2.6 recurse now explicitly distills state before launching fresh context. Only findings.md, workflow_state.json, task_plan.md, and the next AAG contract are passed forward — keeping new invocations in the SFT comfort zone (~4k tokens). https://claude.ai/code/session_01AR3EbNKosxBD5PocKkMSMd
📝 WalkthroughWalkthroughAdds per-subtask AAG/MAP_Contract artifacts and enforces a contract-driven protocol across MAP: decomposer emits aag_contracts, Actor prompts require MAP_Contract and must compile to MAP_Written, Research produces distilled Findings, Monitor performs deterministic AAG-based verification, and minimal distilled state is prescribed for continuation between subtasks. Changes
Sequence Diagram(s)mermaid Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Updates the /map-efficient workflow templates to reduce token usage and ambiguity by tightening prompt boundaries, formalizing agent protocols, and introducing a per-subtask AAG (“Actor -> Action -> Goal”) contract used as a lightweight spec.
Changes:
- Add required
aag_contractfield (with examples) to DECOMPOSE requirements. - Replace “AI Packet” markers with
<MAP_Packet>,<MAP_Context>,<MAP_Contract>,<MAP_Written>semantic brackets and add deterministic protocol checklists for Actor/Monitor. - Add explicit research output distillation rules and a “Context Distillation” recurse guidance section.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| src/mapify_cli/templates/commands/map-efficient.md | Updates the packaged map-efficient command template with semantic brackets, AAG contracts, and distillation guidance. |
| .claude/commands/map-efficient.md | Mirrors the same workflow/prompt updates for the in-repo Claude command definition. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| # Build XML packet | ||
| # Build versioned, scoped XML packet with semantic brackets | ||
| # Format: <MAP_Packet subtask="ST-XXX" v="1.0" risk="low|medium|high"> |
There was a problem hiding this comment.
The comment says the XML packet format is <MAP_Packet ...>, but create_xml_packet(subtask) (in .map/scripts/map_step_runner.py) actually emits <SUBTASK_ST_XXX>... without the MAP_Packet wrapper. This is misleading for anyone following the workflow; either update the text to reflect the actual packet format or change the packet generator to wrap the output in <MAP_Packet ...> as described.
| # Format: <MAP_Packet subtask="ST-XXX" v="1.0" risk="low|medium|high"> | |
| # Format: <SUBTASK_ST_XXX v="1.0" risk="low|medium|high">...</SUBTASK_ST_XXX> |
| - If tests fail: valid=false + failure output | ||
| - If all pass: valid=true + contract_compliant=true""" | ||
| ) | ||
| ``` |
There was a problem hiding this comment.
There’s now a mismatched Markdown code fence: this block is closed at line 293, but there is another standalone ``` later (after the “After Monitor returns” pseudo-code). That later fence will start a new code block and can break rendering of the remainder of the document. Remove the extra fence or move the closing fence so the section has balanced code blocks.
| ``` |
|
|
||
| # Build XML packet | ||
| # Build versioned, scoped XML packet with semantic brackets | ||
| # Format: <MAP_Packet subtask="ST-XXX" v="1.0" risk="low|medium|high"> |
There was a problem hiding this comment.
The comment says the XML packet format is <MAP_Packet ...>, but create_xml_packet(subtask) (in .map/scripts/map_step_runner.py) actually emits <SUBTASK_ST_XXX>... without the MAP_Packet wrapper. This is misleading for anyone following the workflow; either update the text to reflect the actual packet format or change the packet generator to wrap the output in <MAP_Packet ...> as described.
| # Format: <MAP_Packet subtask="ST-XXX" v="1.0" risk="low|medium|high"> | |
| # Actual format emitted by create_xml_packet: | |
| # <SUBTASK_ST_XXX v="1.0" risk="low|medium|high"> ... </SUBTASK_ST_XXX> |
| - If all pass: valid=true + contract_compliant=true""" | ||
| ) | ||
| ``` | ||
|
|
There was a problem hiding this comment.
There’s now a mismatched Markdown code fence: this block is closed at line 293, but there is another standalone ``` later (after the “After Monitor returns” pseudo-code). That later fence will start a new code block and can break rendering of the remainder of the document. Remove the extra fence or move the closing fence so the section has balanced code blocks.
| ```python |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@src/mapify_cli/templates/commands/map-efficient.md`:
- Around line 92-93: The workflow state currently references saving
aag_contracts but the INIT_STATE in workflow_state.json (and the comment before
calling map_orchestrator.py validate_step) doesn't define where to store them;
update the state schema to explicitly include aag_contracts and document its
shape — choose and implement one of: (1) an array parallel to subtask_sequence
(aag_contracts: [ ... ]), (2) embedded within each subtask object (add
aag_contract field to each entry in subtask_sequence), or (3) a mapping from
subtask_id to contract (aag_contracts: { "<subtask_id>": { ... } }). Modify
INIT_STATE to include the chosen aag_contracts structure and update the comment
near the map_orchestrator.py validate_step call to describe that exact storage
format so downstream code (e.g., functions processing subtask_sequence or
reading workflow_state.json) knows where to find contracts.
- Around line 80-90: The PR adds a required "aag_contract" field and shifts task
decomposition/actor/monitor/context behavior to be contract-driven (references:
aag_contract, Actor prompts, Monitor validation, context distillation in
map-efficient.md), so update user-facing docs to reflect this new workflow: add
examples of the AAG contract format and a minimal quick-start in README.md,
expand docs/USAGE.md with CLI usage showing how to supply aag_contract and
test_strategy keys (unit/integration/e2e), and update docs/ARCHITECTURE.md to
describe contract-driven execution, decomposition, actor behavior, and monitor
validation steps including sample AAG lines and expected verification outcomes.
🧹 Nitpick comments (1)
src/mapify_cli/templates/commands/map-efficient.md (1)
238-259: Missing format definitions for MAP_Context and potentially restrictive protocol guidance.
MAP_Context format undefined: Line 244-246 references "top context_patterns from mem0 + relevance_score" but the actual format is not specified. Actors need to know the structure (JSON? XML? key-value pairs?).
Overly prescriptive protocol: Line 256 states "translate MAP_Contract into code (no reasoning about WHAT, only HOW)". This may be too restrictive—understanding the "what" (requirements, edge cases, context) is often necessary for correct implementation. The guidance should encourage understanding the contract's intent while focusing implementation effort on the "how".
📐 Proposed improvements
Add MAP_Context format example after line 246:
Example MAP_Context format: ```json [ { "pattern": "Use JWT validation with 15min expiry", "relevance_score": 0.92, "source": "branch:feat-auth" } ]Soften line 256:
-4. Implement: translate MAP_Contract into code (no reasoning about WHAT, only HOW) +4. Implement: translate MAP_Contract into code (focus on implementation, contract defines requirements)
| - Include `test_strategy` with unit/integration/e2e keys | ||
| - Include `aag_contract` (one-line pseudocode: Actor -> Action -> Goal) | ||
|
|
||
| AAG Contract format (REQUIRED per subtask): | ||
| "aag_contract": "AuthService -> validate(token) -> returns 401|200 with user_id" | ||
| "aag_contract": "ProjectModel -> add_field(archived_at: DateTime?) -> migration passes" | ||
| "aag_contract": "RateLimiter -> decorate(endpoint, 100/min) -> returns 429 when exceeded" | ||
|
|
||
| Purpose: Actor compiles this line into code. Monitor verifies against it. | ||
| This eliminates reasoning overhead — the contract IS the specification.""" | ||
| ) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, find documentation files in the repository
find . -type f \( -name "README.md" -o -name "USAGE.md" -o -name "ARCHITECTURE.md" \) | head -20Repository: azalio/map-framework
Length of output: 272
🏁 Script executed:
# Search for any AAG contract mentions in documentation files
rg -l "aag_contract|AAG.*contract" --type md -iRepository: azalio/map-framework
Length of output: 114
🏁 Script executed:
# Check README.md for workflow/contract mentions
head -100 ./README.md | cat -nRepository: azalio/map-framework
Length of output: 75
🏁 Script executed:
# Check docs/USAGE.md for any contract-related content
head -80 ./docs/USAGE.md | cat -nRepository: azalio/map-framework
Length of output: 3803
🏁 Script executed:
# Check docs/ARCHITECTURE.md for system design sections
head -80 ./docs/ARCHITECTURE.md | cat -nRepository: azalio/map-framework
Length of output: 5303
Documentation updates required for AAG contract integration.
This PR introduces AAG contracts as a core workflow feature, which significantly changes user-facing behavior:
- Task decomposition now requires
aag_contractfield (lines 82-88) - Actor prompts are contract-driven (lines 238-259)
- Monitor validation includes contract compliance (lines 268-293)
- Context distillation procedures affect workflow execution (lines 424-450)
Per learnings, when changing user-facing behavior, update:
README.md(quick-start guide with AAG contract examples)docs/USAGE.md(workflows and CLI usage with contract format)docs/ARCHITECTURE.md(system design explaining contract-driven execution)
🤖 Prompt for AI Agents
In `@src/mapify_cli/templates/commands/map-efficient.md` around lines 80 - 90, The
PR adds a required "aag_contract" field and shifts task
decomposition/actor/monitor/context behavior to be contract-driven (references:
aag_contract, Actor prompts, Monitor validation, context distillation in
map-efficient.md), so update user-facing docs to reflect this new workflow: add
examples of the AAG contract format and a minimal quick-start in README.md,
expand docs/USAGE.md with CLI usage showing how to supply aag_contract and
test_strategy keys (unit/integration/e2e), and update docs/ARCHITECTURE.md to
describe contract-driven execution, decomposition, actor behavior, and monitor
validation steps including sample AAG lines and expected verification outcomes.
| # After decomposer returns: extract subtask sequence + aag_contracts, save to state | ||
| # Update state: python3 .map/scripts/map_orchestrator.py validate_step "1.0" |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Clarify how aag_contracts are structured in workflow state.
The comment indicates that aag_contracts should be saved to state, but the workflow_state.json structure defined at lines 169-179 doesn't include an aag_contracts field.
Specify how aag_contracts are stored: as a separate array parallel to subtask_sequence, embedded within subtask objects, or as a subtask_id-to-contract mapping?
📋 Proposed state structure clarification
Add to the INIT_STATE phase (lines 169-179):
{
"workflow": "map-efficient",
"started_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"current_subtask": null,
"current_state": "INITIALIZED",
"completed_steps": {},
"pending_steps": {},
- "subtask_sequence": []
+ "subtask_sequence": [],
+ "aag_contracts": {}
}Or clarify in the comment at line 92:
-# After decomposer returns: extract subtask sequence + aag_contracts, save to state
+# After decomposer returns: extract subtask sequence + aag_contracts
+# Save to state as: state["aag_contracts"] = {subtask_id: contract_string, ...}🤖 Prompt for AI Agents
In `@src/mapify_cli/templates/commands/map-efficient.md` around lines 92 - 93, The
workflow state currently references saving aag_contracts but the INIT_STATE in
workflow_state.json (and the comment before calling map_orchestrator.py
validate_step) doesn't define where to store them; update the state schema to
explicitly include aag_contracts and document its shape — choose and implement
one of: (1) an array parallel to subtask_sequence (aag_contracts: [ ... ]), (2)
embedded within each subtask object (add aag_contract field to each entry in
subtask_sequence), or (3) a mapping from subtask_id to contract (aag_contracts:
{ "<subtask_id>": { ... } }). Modify INIT_STATE to include the chosen
aag_contracts structure and update the comment near the map_orchestrator.py
validate_step call to describe that exact storage format so downstream code
(e.g., functions processing subtask_sequence or reading workflow_state.json)
knows where to find contracts.
1. Identity deinfestation: Replace "You are a senior software engineer" and "You are a meticulous code reviewer" with Protocol-Driven System descriptions. Agents execute deterministic checklists, not personas. 2. AAG Specification Contract: Add mandatory Section 1 to Actor output — a one-line pseudocode (Actor -> Action -> Goal) that anchors implementation intent BEFORE any code is written. Eliminates "reasoning about what to build" overhead (~30% token savings). 3. Semantic Brackets: Rename all generic XML tags to unique signatures: <output_format> → <Actor_Output_v3_1> <quality_controls> → <Actor_Quality_v3_1> <task> → <MAP_Subtask_Intent> <context> → <MAP_Project_Context> <mcp_protocol> → <Actor_MCP_Protocol> etc. Gives model 100% certainty on section boundaries. 4. SFT Comfort Zone: Add token discipline checklist — functions ~100 lines, total output 50-300 lines per subtask, split if exceeding. 5. Style vs Logic isolation: Replace vague "Follow style guide" with 6-step Coding Standards Protocol — numbered, deterministic, no guessing "how seniors write". https://claude.ai/code/session_01AR3EbNKosxBD5PocKkMSMd
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In @.claude/agents/actor.md:
- Around line 293-298: The fenced code block showing AAG examples lacks a
language tag (triggering markdownlint MD040); update the block starting with the
lines containing AuthService, ProjectModel, RateLimiter, and UserService to
include a language identifier (e.g., add ```text or ```txt immediately after the
opening fence) so the code fence becomes ```text ... ``` and the linter warning
is resolved.
In `@src/mapify_cli/templates/agents/actor.md`:
- Around line 293-298: The fenced code block containing the AAG examples (lines
referencing AuthService, ProjectModel, RateLimiter, UserService) is missing a
language tag; update the opening fence from ``` to a language-specific fence
such as ```text (or ```yaml/```json if you prefer) so markdownlint MD040 stops
flagging it—locate the block with the lines starting "AuthService ->
validate(...)" and change the opening triple backticks to include the chosen
language.
In `@src/mapify_cli/templates/agents/monitor.md`:
- Around line 11-12: The user-facing docs weren’t updated to reflect the
Monitor’s new protocol-driven workflow: update README.md (quick-start),
docs/USAGE.md (workflows and CLI usage), and docs/ARCHITECTURE.md (system
design/agents) to describe that the Monitor is now a "Protocol-Driven Validation
System" that deterministically verifies Actor artifacts against the AAG contract
(mentioning the changed contract-first flow, expected inputs/outputs, CLI
flags/subcommands that invoke Monitor, and any behavioral differences such as
deterministic checklist execution and non-opinionated validation), and ensure
examples, command usage, and architecture diagrams/text reference the Monitor
and AAG contract consistently.
| ``` | ||
| AuthService -> validate(token: JWT) -> returns 401|200 with user_id | ||
| ProjectModel -> add_field(archived_at: DateTime?) -> migration passes, null=active | ||
| RateLimiter -> decorate(endpoint, limit=100/min) -> returns 429 when exceeded | ||
| UserService -> register(email, password) -> creates user, returns 201 with JWT | ||
| ``` |
There was a problem hiding this comment.
Add a language to this fenced code block.
markdownlint MD040 flags this block; specify a language for the AAG examples to keep lint clean.
✅ Suggested fix
-```
+```text
AuthService -> validate(token: JWT) -> returns 401|200 with user_id
ProjectModel -> add_field(archived_at: DateTime?) -> migration passes, null=active
RateLimiter -> decorate(endpoint, limit=100/min) -> returns 429 when exceeded
UserService -> register(email, password) -> creates user, returns 201 with JWT</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.20.0)</summary>
[warning] 293-293: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In @.claude/agents/actor.md around lines 293 - 298, The fenced code block
showing AAG examples lacks a language tag (triggering markdownlint MD040);
update the block starting with the lines containing AuthService, ProjectModel,
RateLimiter, and UserService to include a language identifier (e.g., add text or txt immediately after the opening fence) so the code fence becomes text ... and the linter warning is resolved.
</details>
<!-- fingerprinting:phantom:triton:eagle -->
<!-- This is an auto-generated comment by CodeRabbit -->
| ``` | ||
| AuthService -> validate(token: JWT) -> returns 401|200 with user_id | ||
| ProjectModel -> add_field(archived_at: DateTime?) -> migration passes, null=active | ||
| RateLimiter -> decorate(endpoint, limit=100/min) -> returns 429 when exceeded | ||
| UserService -> register(email, password) -> creates user, returns 201 with JWT | ||
| ``` |
There was a problem hiding this comment.
Add a language to this fenced code block.
markdownlint MD040 flags this block; specify a language for the AAG examples to keep lint clean.
✅ Suggested fix
-```
+```text
AuthService -> validate(token: JWT) -> returns 401|200 with user_id
ProjectModel -> add_field(archived_at: DateTime?) -> migration passes, null=active
RateLimiter -> decorate(endpoint, limit=100/min) -> returns 429 when exceeded
UserService -> register(email, password) -> creates user, returns 201 with JWT</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.20.0)</summary>
[warning] 293-293: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In @src/mapify_cli/templates/agents/actor.md around lines 293 - 298, The fenced
code block containing the AAG examples (lines referencing AuthService,
ProjectModel, RateLimiter, UserService) is missing a language tag; update the
opening fence from to a language-specific fence such astext (or
yaml/json if you prefer) so markdownlint MD040 stops flagging it—locate
the block with the lines starting "AuthService -> validate(...)" and change the
opening triple backticks to include the chosen language.
</details>
<!-- fingerprinting:phantom:triton:eagle -->
<!-- This is an auto-generated comment by CodeRabbit -->
| You are a Protocol-Driven Validation System. Your objective: verify that Actor's code artifacts satisfy the AAG contract, pass all tests, and meet production quality gates. You do not "review like an expert" — you execute a deterministic validation checklist. | ||
|
|
There was a problem hiding this comment.
Update user-facing docs for the new protocol-driven workflow.
This changes how the Monitor behaves and should be reflected in README/USAGE/ARCHITECTURE so users understand the contract-first flow.
Based on learnings: When changing user-facing behavior, update relevant documentation files: README.md (quick-start), docs/USAGE.md (workflows and CLI usage), and docs/ARCHITECTURE.md (system design / agents).
🤖 Prompt for AI Agents
In `@src/mapify_cli/templates/agents/monitor.md` around lines 11 - 12, The
user-facing docs weren’t updated to reflect the Monitor’s new protocol-driven
workflow: update README.md (quick-start), docs/USAGE.md (workflows and CLI
usage), and docs/ARCHITECTURE.md (system design/agents) to describe that the
Monitor is now a "Protocol-Driven Validation System" that deterministically
verifies Actor artifacts against the AAG contract (mentioning the changed
contract-first flow, expected inputs/outputs, CLI flags/subcommands that invoke
Monitor, and any behavioral differences such as deterministic checklist
execution and non-opinionated validation), and ensure examples, command usage,
and architecture diagrams/text reference the Monitor and AAG contract
consistently.
1. Contract-Based Verification: Replace "adversarial reviewer with 10+ years experience" role with Protocol-Driven Validation System. Monitor now executes a 5-step contract verification sequence: parse AAG -> verify Goal -> verify Action -> verify scope -> quality gates. 2. Deterministic REJECT: AAG contract violation is now AUTO-REJECT #1. If implementation deviates from Actor -> Action -> Goal, valid=false regardless of code aesthetics. The contract IS the specification. 3. Intent Comments Check: Added AUTO-REJECT #9 — missing `# Intent:` comments on non-obvious logic blocks, or removal of existing intent comments. Ensures next agent in the chain is never "blind". 4. 10-Dimension Cleanup: Replaced "Check dimensions even if early issues found" with "Execute validation protocol for each dimension sequentially. Do NOT short-circuit." Protocol > vague instruction. 5. Semantic Brackets: Renamed all 16 generic XML tags to Monitor-scoped signatures (<adversarial_reviewer> -> <Monitor_Contract_Verification_v2_9>, <output_format> -> <Monitor_Output_v2_9>, etc.). Eliminates cross-agent tag collision in shared context windows. https://claude.ai/code/session_01AR3EbNKosxBD5PocKkMSMd
…intent-inspection Five optimizations applied: 1. Identity deinfestation: "Compressed Context Acquisition System" replaces persona 2. Semantic brackets: Research_Findings_v1_0, Research_Query_v1_0, Research_Project_Context, Research_Patterns_ACE 3. AAG-filtering: Search flow parses AAG contract keywords, boosts relevance_score +0.1 for matches 4. Protocol-based degradation: FALLBACK-SEQUENCE-04 replaces informal fallback instructions 5. Intent-inspection: has_intent field + 0.9x penalty for code without # Intent: comments https://claude.ai/code/session_01AR3EbNKosxBD5PocKkMSMd
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.claude/agents/monitor.md (1)
11-83:⚠️ Potential issue | 🟡 MinorDocument the AAG contract-driven validation protocol changes in user-facing documentation.
The Monitor agent now implements Protocol-Driven Validation (AAG contract verification, deterministic AUTO-REJECT rules including missing intent comments, contract-based verification sequence). This significant behavioral change must be documented in:
README.md— quick-start should mention AAG contracts and intent comment requirementsdocs/USAGE.md— workflows should describe contract-first validation flowdocs/ARCHITECTURE.md— system design should explain AAG contract architecture and agent coordination
🤖 Fix all issues with AI agents
In @.claude/agents/research-agent.md:
- Around line 162-173: Add a language identifier to the fenced code block for
FALLBACK-SEQUENCE-04 by changing the opening fence from ``` to ```text (or
```plaintext) so markdownlint MD040 is satisfied; locate the block that begins
with the token FALLBACK-SEQUENCE-04 and update the opening fence to include the
language identifier while leaving the block contents unchanged.
In `@src/mapify_cli/templates/agents/research-agent.md`:
- Around line 162-173: The fenced code block for FALLBACK-SEQUENCE-04 is missing
a language identifier which triggers MD040; update the opening fence for the
block that begins with "FALLBACK-SEQUENCE-04:" to include a language tag such as
"text" or "plaintext" (e.g., change ``` to ```text) so the code block is
explicitly identified while leaving the block content unchanged.
| ``` | ||
| FALLBACK-SEQUENCE-04: | ||
| STEP 1: Set status = "DEGRADED_MODE", search_method = "glob_grep_fallback" | ||
| STEP 2: Execute Glob with file patterns from query → collect file list | ||
| STEP 3: Execute Grep with AAG keywords (Actor, Action, Goal terms) → collect matches | ||
| STEP 4: For top 10 matches by line count: Read signature (first 5 lines of function) | ||
| STEP 5: Set confidence *= 0.7 (precision penalty) | ||
| STEP 6: IF confidence < 0.5 → add to executive_summary: | ||
| "Low confidence in degraded mode. Consider manual review." | ||
| STEP 7: Apply AAG-filter and intent-inspection (same as primary path) | ||
| STEP 8: Return JSON with same schema — output format is invariant | ||
| ``` |
There was a problem hiding this comment.
Add language identifier to fenced code block.
The fenced code block starting at line 162 is missing a language identifier, triggering a markdownlint warning (MD040). Since this is a pseudo-code protocol specification, add a language identifier like text or plaintext to the opening fence.
📝 Proposed fix
-```
+```text
FALLBACK-SEQUENCE-04:
STEP 1: Set status = "DEGRADED_MODE", search_method = "glob_grep_fallback"🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
[warning] 162-162: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In @.claude/agents/research-agent.md around lines 162 - 173, Add a language
identifier to the fenced code block for FALLBACK-SEQUENCE-04 by changing the
opening fence from ``` to ```text (or ```plaintext) so markdownlint MD040 is
satisfied; locate the block that begins with the token FALLBACK-SEQUENCE-04 and
update the opening fence to include the language identifier while leaving the
block contents unchanged.
- research-agent.md: Replace ChunkHound MCP primary + fallback architecture with single built-in tools search protocol (Glob + Grep + Read). Remove DEGRADED_MODE status, simplify search_method values. - .gitignore: Remove .chunkhound.json and .chunkhound/ entries - tests: Replace ChunkHound example with generic "my-custom-server" https://claude.ai/code/session_01AR3EbNKosxBD5PocKkMSMd
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/mapify_cli/templates/agents/research-agent.md (1)
1-299:⚠️ Potential issue | 🟠 MajorUpdate user-facing documentation to explain AAG contract-driven protocol and new features.
The research agent introduces significant new user-facing features:
- AAG contract parsing (Actor/Action/Goal keyword extraction from prompts)
- Intent-inspection with
has_intentoutput field- Relevance scoring with AAG-based boosting
- Versioned semantic tags (
<Research_Findings_v1_0>,<Research_Query_v1_0>)None of these features are documented in
README.md,docs/USAGE.md, ordocs/ARCHITECTURE.md. Update these documentation files to explain the new protocol steps, output fields, and how users interact with the AAG contract format.
🤖 Fix all issues with AI agents
In @.claude/agents/research-agent.md:
- Around line 11-23: Update the user-facing docs to describe the new "COMPRESSED
CONTEXT ACQUISITION PROTOCOL": add the six numbered steps (Parse AAG contract →
Extract Actor/Action/Goal, Search codebase, AAG-filter results, Intent-inspect,
Compress output (MAX 1500 tokens, signatures + line ranges), Return JSON) plus
the hard constraints (NEVER return raw file contents, exceed 1500 tokens,
include irrelevant code, or skip confidence/has_intent) and an example of the
expected OUTPUT FORMAT; apply these changes to README.md (quick-start/summary),
docs/USAGE.md (workflows and CLI expectations), and docs/ARCHITECTURE.md (system
design/agents) so each doc clearly states the protocol name, the step list, the
token/format constraints, and where callers should expect JSON responses.
In `@src/mapify_cli/templates/agents/research-agent.md`:
- Around line 152-163: The fenced code block containing the SEARCH-PROTOCOL-01
protocol lacks a language identifier which triggers MD040; update the opening
fence for that block to include a language (e.g., add "text" after the
backticks) so the block becomes a fenced code block with a language identifier
and resolves the markdownlint warning while keeping the protocol content
unchanged.
🧹 Nitpick comments (2)
.claude/agents/research-agent.md (1)
1-6: Sync templates and run template-sync tests for.claude/agentschanges.Please copy this change to
src/mapify_cli/templates/agents/research-agent.mdand runpytest tests/test_template_sync.py -v. As per coding guidelines, “If you change anything under.claude/that is shipped to users, you MUST copy it to the matching path undersrc/mapify_cli/templates/… Sync viamake sync-templates…” and “Runpytest tests/test_template_sync.py -vto enforce agent template sync verification.”src/mapify_cli/templates/agents/research-agent.md (1)
248-299: Consider consistent versioning for all dynamic content tags.The dynamic content section uses a mix of versioned (
Research_Query_v1_0) and unversioned (Research_Project_Context,Research_Patterns_ACE) tags. For consistency with the "Semantic Brackets" PR objective and to future-proof schema evolution, consider versioning all dynamic content tags.♻️ Example versioning approach
-<Research_Project_Context> +<Research_Project_Context_v1_0> ## Project Information ... -</Research_Project_Context> +</Research_Project_Context_v1_0> -<Research_Patterns_ACE> +<Research_Patterns_v1_0> ## Available Patterns (ACE Learning) ... -</Research_Patterns_ACE> +</Research_Patterns_v1_0>
| ┌─────────────────────────────────────────────────────────────────────┐ | ||
| │ RESEARCH AGENT PROTOCOL │ | ||
| │ COMPRESSED CONTEXT ACQUISITION PROTOCOL │ | ||
| ├─────────────────────────────────────────────────────────────────────┤ | ||
| │ 1. Search codebase → Use ChunkHound MCP or fallback tools │ | ||
| │ 2. Extract relevant → Signatures + line ranges only │ | ||
| │ 3. Compress output → MAX 1500 tokens total │ | ||
| │ 4. Return JSON → See OUTPUT FORMAT below │ | ||
| │ 1. Parse AAG contract → Extract Actor/Action/Goal keywords │ | ||
| │ 2. Search codebase → Glob + Grep + Read (built-in tools) │ | ||
| │ 3. AAG-filter results → Boost relevance for contract-matching code │ | ||
| │ 4. Intent-inspect → Check for # Intent: comments per location │ | ||
| │ 5. Compress output → MAX 1500 tokens, signatures + line ranges │ | ||
| │ 6. Return JSON → See OUTPUT FORMAT below │ | ||
| ├─────────────────────────────────────────────────────────────────────┤ | ||
| │ NEVER: Return raw file contents | Exceed 1500 tokens output │ | ||
| │ Include irrelevant code | Skip confidence score │ | ||
| │ NEVER: Return raw file contents | Exceed 1500 tokens output │ | ||
| │ Include irrelevant code | Skip confidence or has_intent │ | ||
| └─────────────────────────────────────────────────────────────────────┘ |
There was a problem hiding this comment.
Update user-facing docs to reflect the new protocol/format.
This is a user-facing behavior change; please update README.md, docs/USAGE.md, and docs/ARCHITECTURE.md accordingly. Based on learnings, “When changing user-facing behavior, update relevant docs: README.md (quick-start), docs/USAGE.md (workflows and CLI usage), and docs/ARCHITECTURE.md (system design / agents).”
🤖 Prompt for AI Agents
In @.claude/agents/research-agent.md around lines 11 - 23, Update the
user-facing docs to describe the new "COMPRESSED CONTEXT ACQUISITION PROTOCOL":
add the six numbered steps (Parse AAG contract → Extract Actor/Action/Goal,
Search codebase, AAG-filter results, Intent-inspect, Compress output (MAX 1500
tokens, signatures + line ranges), Return JSON) plus the hard constraints (NEVER
return raw file contents, exceed 1500 tokens, include irrelevant code, or skip
confidence/has_intent) and an example of the expected OUTPUT FORMAT; apply these
changes to README.md (quick-start/summary), docs/USAGE.md (workflows and CLI
expectations), and docs/ARCHITECTURE.md (system design/agents) so each doc
clearly states the protocol name, the step list, the token/format constraints,
and where callers should expect JSON responses.
| ``` | ||
| SEARCH-PROTOCOL-01: | ||
| STEP 1: Parse AAG contract from prompt (if provided) — extract Actor, Action, Goal keywords | ||
| STEP 2: Execute Glob with file patterns from query → collect file list | ||
| STEP 3: Execute Grep with query symbols + AAG keywords → collect matches | ||
| STEP 4: For top 10 matches: Read signature (first 5 lines of function/class) | ||
| STEP 5: AAG-filter — re-rank by proximity to AAG keywords (Actor class, Action method, Goal type). Boost relevance_score by +0.1 for matches | ||
| STEP 6: Intent-inspect — check for # Intent: comments in each location | ||
| STEP 7: IF confidence < 0.5 → add to executive_summary: | ||
| "Low confidence results. Consider manual review." | ||
| STEP 8: Return JSON (output format is invariant) | ||
| ``` |
There was a problem hiding this comment.
Add language identifier to fenced code block.
The fenced code block starting at line 152 is missing a language identifier, triggering a markdownlint warning (MD040). Since this is a protocol specification, add a language identifier like text to the opening fence.
📝 Proposed fix
-```
+```text
SEARCH-PROTOCOL-01:
STEP 1: Parse AAG contract from prompt (if provided) — extract Actor, Action, Goal keywords📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` | |
| SEARCH-PROTOCOL-01: | |
| STEP 1: Parse AAG contract from prompt (if provided) — extract Actor, Action, Goal keywords | |
| STEP 2: Execute Glob with file patterns from query → collect file list | |
| STEP 3: Execute Grep with query symbols + AAG keywords → collect matches | |
| STEP 4: For top 10 matches: Read signature (first 5 lines of function/class) | |
| STEP 5: AAG-filter — re-rank by proximity to AAG keywords (Actor class, Action method, Goal type). Boost relevance_score by +0.1 for matches | |
| STEP 6: Intent-inspect — check for # Intent: comments in each location | |
| STEP 7: IF confidence < 0.5 → add to executive_summary: | |
| "Low confidence results. Consider manual review." | |
| STEP 8: Return JSON (output format is invariant) | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
[warning] 152-152: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@src/mapify_cli/templates/agents/research-agent.md` around lines 152 - 163,
The fenced code block containing the SEARCH-PROTOCOL-01 protocol lacks a
language identifier which triggers MD040; update the opening fence for that
block to include a language (e.g., add "text" after the backticks) so the block
becomes a fenced code block with a language identifier and resolves the
markdownlint warning while keeping the protocol content unchanged.
…racts + GRACE graph Five optimizations applied: 1. Identity deinfestation: "Goal Decomposition System" replaces "software architect" persona 2. AAG contracts: mandatory aag_contract field per subtask (Actor -> Action -> Goal), added to schema, field docs, all 4 example subtasks, and final checklist 3. Semantic brackets: 11 generic XML tags renamed to Decomposer-scoped signatures (Decomposition_Algorithm_v2_4, Decomposer_Output_v2_4, Decomposer_MCP_Integration_v2_4, etc.) 4. Architecture graph: new analysis.architecture_graph_summary field — pseudocode DAG of affected classes/modules, written BEFORE decomposition begins 5. SFT comfort zone: ~4000 token constraint per subtask in algorithm, atomicity check, and critical decision points — forces further splitting for Actor precision https://claude.ai/code/session_01AR3EbNKosxBD5PocKkMSMd
…stillation Five optimizations to the Architect phase: 1. Architecture Graph (Step 4): REQUIRED pseudocode graph of affected classes/modules before decomposition — decomposer gets a skeleton 2. AAG Contracts (Step 5 & 6): mandatory aag_contract per subtask in task_plan.md and aag_contracts map in workflow_state.json — turns the plan from a "todo list" into an executable protocol 3. Semantic Brackets (Step 6 & 7): <MAP_Plan_v1_0> wraps task plan, _semantic_tag in workflow_state.json — zero-ambiguity parsing 4. Contract Clarity (Step 2): dimension #7 in interview checklist — reject process-goals ("improve auth"), require outcome-goals ("returns 401 for expired tokens") 5. Context Distillation (Step 8): distillation checklist before STOP — ensures plan files are self-contained for fresh executor session, target ≤4000 tokens per subtask context https://claude.ai/code/session_01AR3EbNKosxBD5PocKkMSMd
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.claude/agents/task-decomposer.md (1)
6-6:⚠️ Potential issue | 🟡 MinorUpdate the stale
last_updatedtimestamp.The
last_updatedfield shows2025-11-27, but this PR is dated2026-02-08. Update to reflect the actual modification date.📅 Proposed fix
-last_updated: 2025-11-27 +last_updated: 2026-02-08
🤖 Fix all issues with AI agents
In @.claude/agents/task-decomposer.md:
- Around line 13-17: Update user docs to reflect the new task decomposition
protocol: add a section in docs/USAGE.md describing the decomposition workflow
and required output fields (AAG contract format, architecture_graph_summary, and
the ~4000 token output limit), and update docs/ARCHITECTURE.md to explain
protocol changes including semantic versioning expectations and the
deterministic acyclic graph (DAG) constraints; reference the task-decomposer.md
definitions (AAG, architecture_graph_summary) and ensure examples show the exact
machine-readable blueprint format and versioning metadata so users know the
required inputs and outputs before using the decomposer.
🧹 Nitpick comments (4)
.claude/agents/task-decomposer.md (4)
49-51: Clarify the ~4000 token SFT constraint rationale.The constraint "implementation + tests ≤ ~4000 tokens" is introduced without explaining:
- What "SFT" stands for (Supervised Fine-Tuning)
- Why 4000 tokens is the threshold
- How decomposers should estimate token count
- What happens if the limit is exceeded
Consider adding a brief explanation or referencing documentation that justifies this limit.
📝 Suggested clarification
│ 5. DECOMPOSE INTO SUBTASKS │ │ └─ Each subtask: atomic, testable, single responsibility │ -│ └─ SFT constraint: implementation + tests ≤ ~4000 tokens │ -│ └─ If subtask exceeds ~4000 tokens → MUST split further │ +│ └─ SFT constraint: implementation + tests ≤ ~4000 tokens (~300 LOC) │ +│ (Supervised Fine-Tuning models perform best within this context window) │ +│ └─ If subtask exceeds ~4000 tokens → MUST split further │ +│ (Use `wc -w` or token counter to estimate; rough guide: 1 token ≈ 0.75 words) │
206-211: Enhance architecture_graph_summary guidance with additional examples.The
architecture_graph_summaryis a new required field, but only one simple example is provided. Consider adding examples for:
- Multi-layer architectures (UI → Service → Repository → Database)
- Multiple relationships between the same entities
- Complex dependency graphs with 5+ nodes
This would help decomposers understand the expected format for non-trivial features.
📚 Suggested additional examples
Add to the field requirements section:
**Examples of architecture_graph_summary**: - Simple: `"UserModel -[has_many]-> Project -[has_one]-> ArchiveState"` - Multi-layer: `"UI/ProjectList -[calls]-> ProjectService -[uses]-> ProjectRepo -[queries]-> ProjectModel"` - Multiple relationships: `"User -[owns]-> Project -[has_many]-> Task; User -[collaborates_on]-> Project"` - With external deps: `"AuthService -[calls]-> JWT.encode(); RateLimiter -[uses]-> Redis.incr()"`
257-264: Clarify the relationship betweenaag_contractandcontractsarray.Both
aag_contract(line 257) andcontracts(line 251) serve verification purposes, which could confuse users. Theaag_contractis described as the "primary handoff artifact," whilecontractsare "executable assertion patterns."Consider adding a brief note distinguishing their purposes:
aag_contract: High-level Actor → Action → Goal for decomposition/planningcontracts: Low-level executable assertions for runtime verification✨ Suggested clarification
**subtasks[].aag_contract**: REQUIRED one-line contract in `Actor -> Action(params) -> Goal` format - This is the primary handoff artifact to the Actor agent - Actor "compiles" this contract into code; Monitor verifies against it + - Distinct from `contracts` array: AAG is high-level planning; contracts are low-level assertions - Format: `"<Actor> -> <Action>(params) -> <Goal with success criteria>"`
140-140: Clarify the distinction between template version and schema version.The template version is
2.4.0(line 5) with versioned tags likev2_4, but the JSON output requiresschema_version: "2.0"(line 140). This dual versioning could confuse users.Consider adding a brief note explaining:
schema_version: "2.0"= JSON structure version (stable)- Template version
2.4.0= Agent protocol/behavior version (evolving)📖 Suggested clarification
-**schema_version**: Always "2.0" for this schema version +**schema_version**: Always "2.0" for this JSON structure version + - Note: This is distinct from the template version (2.4.0), which tracks agent protocol changes + - schema_version changes only when JSON structure breaks backward compatibilityAlso applies to: 198-198
| You are a Goal Decomposition System. Your objective: translate ambiguous | ||
| high-level goals into a deterministic, acyclic graph (DAG) of atomic | ||
| subtasks — each with an AAG contract (Actor -> Action -> Goal). You do | ||
| not "architect" — you execute a decomposition protocol that outputs a | ||
| machine-readable blueprint for the Actor/Monitor pipeline. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# First, explore the repo structure to understand context
echo "=== Repository structure ==="
git ls-files | head -30
echo -e "\n=== Checking for documentation directories ==="
ls -la | grep -E "README|docs"
echo -e "\n=== Checking task-decomposer.md file ==="
if [ -f ".claude/agents/task-decomposer.md" ]; then
echo "✓ File exists"
wc -l ".claude/agents/task-decomposer.md"
else
echo "✗ File not found"
fiRepository: azalio/map-framework
Length of output: 1258
🏁 Script executed:
#!/bin/bash
# Run the verification script from the review comment
echo "Checking for AAG contract documentation..."
rg "aag_contract|AAG contract|Actor.*Action.*Goal" README.md docs/ 2>/dev/null || echo "⚠️ AAG contract not documented"
echo -e "\nChecking for architecture_graph_summary documentation..."
rg "architecture_graph_summary|architecture graph" README.md docs/ 2>/dev/null || echo "⚠️ Architecture graph not documented"
echo -e "\nChecking for ~4000 token constraint documentation..."
rg "4000 token|SFT.*token|token.*constraint" README.md docs/ 2>/dev/null || echo "⚠️ Token constraints not documented"
echo -e "\nChecking for semantic versioned tags documentation..."
rg "Decomposer_Output_v2_4|semantic.*tag|versioned.*tag" README.md docs/ 2>/dev/null || echo "⚠️ Versioned tags not documented"Repository: azalio/map-framework
Length of output: 414
🏁 Script executed:
#!/bin/bash
# Read the task-decomposer.md file to see what's actually described
echo "=== Content of task-decomposer.md (first 50 lines) ==="
head -50 ".claude/agents/task-decomposer.md"Repository: azalio/map-framework
Length of output: 2753
🏁 Script executed:
#!/bin/bash
# Check what documentation files exist
echo "=== Documentation files ==="
find . -maxdepth 3 -type f \( -name "README.md" -o -name "USAGE.md" -o -name "ARCHITECTURE.md" \) | sortRepository: azalio/map-framework
Length of output: 205
🏁 Script executed:
#!/bin/bash
# Check the content of documentation files to see what they cover
echo "=== README.md content ==="
cat README.md
echo -e "\n=== docs/USAGE.md (first 80 lines) ==="
head -80 docs/USAGE.md
echo -e "\n=== docs/ARCHITECTURE.md (first 80 lines) ==="
head -80 docs/ARCHITECTURE.mdRepository: azalio/map-framework
Length of output: 8039
🏁 Script executed:
#!/bin/bash
# Check the templates directory to see if template sync is needed
echo "=== Checking template sync status ==="
if [ -f "src/mapify_cli/templates/agents/task-decomposer.md" ]; then
echo "Template file exists at: src/mapify_cli/templates/agents/task-decomposer.md"
echo -e "\n=== Comparing .claude and templates versions ==="
diff ".claude/agents/task-decomposer.md" "src/mapify_cli/templates/agents/task-decomposer.md" | head -20
else
echo "Template file does NOT exist at src/mapify_cli/templates/agents/task-decomposer.md"
fi
echo -e "\n=== Checking if sync script exists ==="
if [ -f "scripts/sync-templates.sh" ]; then
echo "✓ Sync script exists"
else
echo "✗ Sync script not found"
fiRepository: azalio/map-framework
Length of output: 288
🏁 Script executed:
#!/bin/bash
# Check more of the task-decomposer.md to understand all changes
echo "=== task-decomposer.md lines 40-120 ==="
sed -n '40,120p' ".claude/agents/task-decomposer.md"
echo -e "\n=== Searching for new concepts in task-decomposer.md ==="
echo "AAG contract mentions:"
rg -n "AAG|aag_contract|Actor.*Action.*Goal" ".claude/agents/task-decomposer.md" | head -5
echo -e "\nArchitecture graph mentions:"
rg -n "architecture_graph|dag_json|architecture" ".claude/agents/task-decomposer.md" | head -5
echo -e "\nToken constraint mentions:"
rg -n "4000.*token|SFT.*token|~4000" ".claude/agents/task-decomposer.md" | head -5
echo -e "\nVersioned tag mentions:"
rg -n "Decomposer_Output|_v2_|semantic.*tag|version.*tag" ".claude/agents/task-decomposer.md" | head -5Repository: azalio/map-framework
Length of output: 5946
Update user-facing documentation to cover new task decomposition protocol changes.
The task-decomposer.md file introduces significant user-facing changes with new required fields (AAG contracts, architecture_graph_summary) and constraints (~4000 token limits, semantic versioning). These must be documented in docs/USAGE.md (decomposition workflows and output format) and docs/ARCHITECTURE.md (agent protocol changes) so users understand the new requirements before using the decomposer.
🤖 Prompt for AI Agents
In @.claude/agents/task-decomposer.md around lines 13 - 17, Update user docs to
reflect the new task decomposition protocol: add a section in docs/USAGE.md
describing the decomposition workflow and required output fields (AAG contract
format, architecture_graph_summary, and the ~4000 token output limit), and
update docs/ARCHITECTURE.md to explain protocol changes including semantic
versioning expectations and the deterministic acyclic graph (DAG) constraints;
reference the task-decomposer.md definitions (AAG, architecture_graph_summary)
and ensure examples show the exact machine-readable blueprint format and
versioning metadata so users know the required inputs and outputs before using
the decomposer.
2 participants
Semantic Brackets: Replace generic
**AI Packet (XML):**markers withversioned
<MAP_Packet>,<MAP_Context>,<MAP_Contract>,<MAP_Written>tags that give agents unambiguous context boundaries.
Protocol over Role: Replace vague "Follow Actor agent protocol" and
generic "Check security, standards" with strict numbered protocol steps
in both ACTOR and MONITOR prompts. Agents now execute a deterministic
checklist rather than interpreting a role description.
Wenyan-style AAG contracts: DECOMPOSE phase now requires an
aag_contractfield per subtask (Actor -> Action -> Goal one-liner). Actor compiles
this directly into code; Monitor verifies against it. Eliminates
reasoning overhead (~30% token savings on Thinking).
Context Distillation: Step 2.6 recurse now explicitly distills state
before launching fresh context. Only findings.md, workflow_state.json,
task_plan.md, and the next AAG contract are passed forward — keeping
new invocations in the SFT comfort zone (~4k tokens).
https://claude.ai/code/session_01AR3EbNKosxBD5PocKkMSMd
Summary by CodeRabbit
Enhancements
Refactor
Documentation
Tests
Chore