agentscaffold 0.2.2__tar.gz → 0.2.4__tar.gz

{agentscaffold-0.2.2 → agentscaffold-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentscaffold
-Version: 0.2.2
+Version: 0.2.4
 Summary: Structured AI-assisted development framework with plan lifecycle, review gates, and continuous improvement.
 Project-URL: Homepage, https://github.com/drobbster/agentscaffold
 Project-URL: Documentation, https://github.com/drobbster/agentscaffold#readme
@@ -92,7 +92,7 @@ Description-Content-Type: text/markdown
 
 **Stop paying for your AI agent to rediscover your codebase every session.**
 
-AgentScaffold is a governance framework and persistent knowledge graph for AI coding agents. It replaces the expensive pattern of agents reading dozens of files, grepping for symbols, and tracing dependencies from scratch -- with a single tool call that returns exactly what the agent needs.
+AgentScaffold is a governance framework and persistent knowledge graph for AI coding agents. It replaces the expensive pattern of agents re-reading files, re-grepping symbols, and re-tracing dependencies from scratch -- with a single tool call that returns exactly what the agent needs.
 
 ## The Problem
 
@@ -101,10 +101,11 @@ Every time you start a new session with Cursor, Claude Code, Codex, or any AI co
 On a moderately complex codebase, a single "understand this module" task can cost **12 file reads + 2 grep searches** before the agent even starts working. A full plan review pulls in **10+ files**. Getting oriented in a new codebase means reading **38+ files**.
 
 This is the hidden cost of agentic development: not the coding, but the *context building*.
+AgentScaffold addresses this by separating one-time indexing from repeated reasoning work.
 
 ## The Solution
 
-AgentScaffold builds a knowledge graph of your codebase -- code structure, dependencies, governance artifacts, session history -- and exposes it through MCP tools that your agent calls instead of reading raw files.
+AgentScaffold builds a knowledge graph of your codebase -- code structure, dependencies, governance artifacts, and session history -- and exposes it through MCP tools that your agent calls instead of reading raw files. Instead of rebuilding context from scratch in every session, the agent retrieves scoped context in one call and moves directly into analysis or implementation.
 
 **Measured results from our latest evaluation harness run (79 scenarios, 100% pass rate):**
 
@@ -125,6 +126,8 @@ We now report two views so results are not sugar-coated:
 - **Capability efficiency (raw):** what the tools can do when selected (58% token and 91% call reduction average).
 - **Behavior-adjusted efficiency:** capability gains multiplied by tool-routing adherence proxy.
 
+In real usage, adjusted values are lower because agents do not always choose tools consistently; replay-based evaluation captures that behavior directly.
+
 Current harness outputs:
 
 | View | Token Reduction | Call Reduction |
@@ -139,7 +142,7 @@ Every tool call your agent doesn't make is money you don't spend on API tokens o
 
 ## What It Does
 
-AgentScaffold combines two capabilities that don't exist together in any other tool:
+AgentScaffold combines two capabilities that are rarely integrated together in a single tool:
 
 ### 1. Agent Governance Framework
 
@@ -151,7 +154,8 @@ A structured development workflow that teaches your AI agent to follow a plan li
 - **Retrospectives**: Post-execution learning that feeds back into the process
 - **Session tracking**: State files that persist context across chat sessions
 
-**Think of it as a virtual sprint team.** Most AI agents work alone -- they take instructions and start coding. AgentScaffold puts your agent on a team. Before it writes a single line of code, the plan faces a devil's advocate who asks "what if this breaks?", an expansion reviewer who asks "what did you miss?", and a domain expert -- a quant architect, a UX designer, a security engineer -- who pressure-tests the approach through the lens of your specific domain. These adversarial reviews catch flawed assumptions, missing edge cases, and architectural blind spots *before* they become bugs in production.
+**Think of it as a virtual sprint team.** Most AI agents work alone -- they take instructions and start coding. AgentScaffold puts your agent on a team.
+Before it writes a single line of code, the plan faces a devil's advocate who asks "what if this breaks?", an expansion reviewer who asks "what did you miss?", and a domain expert -- a quant architect, a UX designer, a security engineer -- who pressure-tests the approach through the lens of your specific domain. These adversarial reviews catch flawed assumptions, missing edge cases, and architectural blind spots *before* they become bugs in production.
 
 After implementation, the sprint continues. A post-implementation review verifies what was built against what was planned. A retrospective captures what worked, what didn't, and what to do differently. Those findings flow into the learnings tracker, which feeds back into the agent's rules and templates -- so the next sprint starts sharper than the last. This is the same continuous improvement loop that makes experienced engineering teams get better over time, applied to your AI agent.
 
@@ -190,6 +194,32 @@ The `init` command scaffolds your project with:
 
 The `index` command builds the knowledge graph at `.scaffold/graph.db`, enabling search, reviews, impact analysis, and session memory.
 
+### Async freshness (low-latency graph updates for MCP)
+
+AgentScaffold supports an async freshness mode for MCP usage. Instead of blocking a tool
+call to re-index, the request path runs a cheap freshness check and returns immediately.
+If the graph looks stale, a background incremental refresh is scheduled (with debounce and
+single-flight locking) while the agent continues working.
+
+Why this design matters:
+
+- Keeps MCP interactions in milliseconds/seconds instead of minutes on large repos
+- Avoids duplicate refresh jobs under parallel tool usage
+- Surfaces explicit freshness metadata (`fresh`, `stale`, `unknown`, `refreshing`) so
+  agents can reason about confidence
+- Preserves strict governance by allowing gate transitions to defer when freshness is
+  required and not yet restored
+
+Configure in `scaffold.yaml`:
+
+```yaml
+freshness:
+  async_enabled: true
+  debounce_seconds: 120
+  gate_strict: false
+  background_queue_enabled: true
+```
+
 ### Install with language support
 
 ```bash
@@ -204,7 +234,23 @@ pip install agentscaffold[all]                # Everything
 
 When you run `scaffold mcp`, these tools become available to your agent.
 
-You don't need to memorize tool names. AgentScaffold ships with **intent descriptions** and an **MCP-first routing policy** -- natural language trigger phrases plus fallback rules that push the agent to use MCP tools first, then allow direct reads/search if output is insufficient. Say "let's review plan 42" and the agent calls `scaffold_prepare_review`. Say "where did we leave off?" and it calls `scaffold_orient`. Run `scaffold agents cursor` (or `windsurf`, `claude`) to generate platform-specific rules that wire this up for your IDE.
+#### Interaction Modes
+
+AgentScaffold supports two complementary ways of working:
+
+- **Natural-language + MCP (interactive)**: describe intent conversationally and let the
+  agent route to the right governance/graph workflow.
+- **Structural CLI commands (explicit/automation)**: use direct `scaffold` commands for
+  deterministic setup, verification, CI, and fallback.
+
+Teams usually get best UX with NL+MCP for day-to-day flow, then use explicit CLI commands
+for verification (`scaffold validate`, `scaffold graph verify`, `scaffold index --incremental`).
+
+If you used the governance framework before knowledge graph integration, see
+[`docs/migrating-governance-to-nl-mcp.md`](docs/migrating-governance-to-nl-mcp.md)
+for a command-first -> hybrid -> NL-first transition path.
+
+You don't need to memorize tool names. AgentScaffold teaches the agent how to interpret user intent in natural conversation, map that intent to the right MCP workflow, and only fall back to direct reads/search when tool output is insufficient. Say "let's review plan 42" and the agent routes to `scaffold_prepare_review`. Say "where did we leave off?" and it routes to `scaffold_orient`. Run `scaffold agents cursor` (or `windsurf`, `claude`) to generate platform-specific rules that wire this behavior into your IDE.
 
 **Composite tools** -- single calls that replace entire multi-step workflows:
 
@@ -220,6 +266,8 @@ You don't need to memorize tool names. AgentScaffold ships with **intent descrip
 | `scaffold_find_studies` | Searching study files by topic, tags, or outcome |
 | `scaffold_find_adrs` | Searching architecture decision records by topic or status |
 
+Use composite tools by default for common workflows; use granular tools when you need targeted control.
+
 **Granular tools** -- building blocks for custom queries:
 
 | Tool | What It Replaces |
@@ -283,9 +331,11 @@ The governance framework is domain-aware. Domain packs teach the adversarial rev
 | embedded | Memory constraints, real-time deadlines, OTA safety |
 | research | Reproducibility, statistical rigor, experiment protocol |
 
+This keeps governance strict where risk is high and lightweight where speed matters, without rewriting the core framework.
+
 ```bash
-scaffold domain add trading
-scaffold domain add webapp
+scaffold domains add trading
+scaffold domains add webapp
 ```
 
 ## Documentation

{agentscaffold-0.2.2 → agentscaffold-0.2.4}/README.md

@@ -2,7 +2,7 @@
 
 **Stop paying for your AI agent to rediscover your codebase every session.**
 
-AgentScaffold is a governance framework and persistent knowledge graph for AI coding agents. It replaces the expensive pattern of agents reading dozens of files, grepping for symbols, and tracing dependencies from scratch -- with a single tool call that returns exactly what the agent needs.
+AgentScaffold is a governance framework and persistent knowledge graph for AI coding agents. It replaces the expensive pattern of agents re-reading files, re-grepping symbols, and re-tracing dependencies from scratch -- with a single tool call that returns exactly what the agent needs.
 
 ## The Problem
 
@@ -11,10 +11,11 @@ Every time you start a new session with Cursor, Claude Code, Codex, or any AI co
 On a moderately complex codebase, a single "understand this module" task can cost **12 file reads + 2 grep searches** before the agent even starts working. A full plan review pulls in **10+ files**. Getting oriented in a new codebase means reading **38+ files**.
 
 This is the hidden cost of agentic development: not the coding, but the *context building*.
+AgentScaffold addresses this by separating one-time indexing from repeated reasoning work.
 
 ## The Solution
 
-AgentScaffold builds a knowledge graph of your codebase -- code structure, dependencies, governance artifacts, session history -- and exposes it through MCP tools that your agent calls instead of reading raw files.
+AgentScaffold builds a knowledge graph of your codebase -- code structure, dependencies, governance artifacts, and session history -- and exposes it through MCP tools that your agent calls instead of reading raw files. Instead of rebuilding context from scratch in every session, the agent retrieves scoped context in one call and moves directly into analysis or implementation.
 
 **Measured results from our latest evaluation harness run (79 scenarios, 100% pass rate):**
 
@@ -35,6 +36,8 @@ We now report two views so results are not sugar-coated:
 - **Capability efficiency (raw):** what the tools can do when selected (58% token and 91% call reduction average).
 - **Behavior-adjusted efficiency:** capability gains multiplied by tool-routing adherence proxy.
 
+In real usage, adjusted values are lower because agents do not always choose tools consistently; replay-based evaluation captures that behavior directly.
+
 Current harness outputs:
 
 | View | Token Reduction | Call Reduction |
@@ -49,7 +52,7 @@ Every tool call your agent doesn't make is money you don't spend on API tokens o
 
 ## What It Does
 
-AgentScaffold combines two capabilities that don't exist together in any other tool:
+AgentScaffold combines two capabilities that are rarely integrated together in a single tool:
 
 ### 1. Agent Governance Framework
 
@@ -61,7 +64,8 @@ A structured development workflow that teaches your AI agent to follow a plan li
 - **Retrospectives**: Post-execution learning that feeds back into the process
 - **Session tracking**: State files that persist context across chat sessions
 
-**Think of it as a virtual sprint team.** Most AI agents work alone -- they take instructions and start coding. AgentScaffold puts your agent on a team. Before it writes a single line of code, the plan faces a devil's advocate who asks "what if this breaks?", an expansion reviewer who asks "what did you miss?", and a domain expert -- a quant architect, a UX designer, a security engineer -- who pressure-tests the approach through the lens of your specific domain. These adversarial reviews catch flawed assumptions, missing edge cases, and architectural blind spots *before* they become bugs in production.
+**Think of it as a virtual sprint team.** Most AI agents work alone -- they take instructions and start coding. AgentScaffold puts your agent on a team.
+Before it writes a single line of code, the plan faces a devil's advocate who asks "what if this breaks?", an expansion reviewer who asks "what did you miss?", and a domain expert -- a quant architect, a UX designer, a security engineer -- who pressure-tests the approach through the lens of your specific domain. These adversarial reviews catch flawed assumptions, missing edge cases, and architectural blind spots *before* they become bugs in production.
 
 After implementation, the sprint continues. A post-implementation review verifies what was built against what was planned. A retrospective captures what worked, what didn't, and what to do differently. Those findings flow into the learnings tracker, which feeds back into the agent's rules and templates -- so the next sprint starts sharper than the last. This is the same continuous improvement loop that makes experienced engineering teams get better over time, applied to your AI agent.
 
@@ -100,6 +104,32 @@ The `init` command scaffolds your project with:
 
 The `index` command builds the knowledge graph at `.scaffold/graph.db`, enabling search, reviews, impact analysis, and session memory.
 
+### Async freshness (low-latency graph updates for MCP)
+
+AgentScaffold supports an async freshness mode for MCP usage. Instead of blocking a tool
+call to re-index, the request path runs a cheap freshness check and returns immediately.
+If the graph looks stale, a background incremental refresh is scheduled (with debounce and
+single-flight locking) while the agent continues working.
+
+Why this design matters:
+
+- Keeps MCP interactions in milliseconds/seconds instead of minutes on large repos
+- Avoids duplicate refresh jobs under parallel tool usage
+- Surfaces explicit freshness metadata (`fresh`, `stale`, `unknown`, `refreshing`) so
+  agents can reason about confidence
+- Preserves strict governance by allowing gate transitions to defer when freshness is
+  required and not yet restored
+
+Configure in `scaffold.yaml`:
+
+```yaml
+freshness:
+  async_enabled: true
+  debounce_seconds: 120
+  gate_strict: false
+  background_queue_enabled: true
+```
+
 ### Install with language support
 
 ```bash
@@ -114,7 +144,23 @@ pip install agentscaffold[all]                # Everything
 
 When you run `scaffold mcp`, these tools become available to your agent.
 
-You don't need to memorize tool names. AgentScaffold ships with **intent descriptions** and an **MCP-first routing policy** -- natural language trigger phrases plus fallback rules that push the agent to use MCP tools first, then allow direct reads/search if output is insufficient. Say "let's review plan 42" and the agent calls `scaffold_prepare_review`. Say "where did we leave off?" and it calls `scaffold_orient`. Run `scaffold agents cursor` (or `windsurf`, `claude`) to generate platform-specific rules that wire this up for your IDE.
+#### Interaction Modes
+
+AgentScaffold supports two complementary ways of working:
+
+- **Natural-language + MCP (interactive)**: describe intent conversationally and let the
+  agent route to the right governance/graph workflow.
+- **Structural CLI commands (explicit/automation)**: use direct `scaffold` commands for
+  deterministic setup, verification, CI, and fallback.
+
+Teams usually get best UX with NL+MCP for day-to-day flow, then use explicit CLI commands
+for verification (`scaffold validate`, `scaffold graph verify`, `scaffold index --incremental`).
+
+If you used the governance framework before knowledge graph integration, see
+[`docs/migrating-governance-to-nl-mcp.md`](docs/migrating-governance-to-nl-mcp.md)
+for a command-first -> hybrid -> NL-first transition path.
+
+You don't need to memorize tool names. AgentScaffold teaches the agent how to interpret user intent in natural conversation, map that intent to the right MCP workflow, and only fall back to direct reads/search when tool output is insufficient. Say "let's review plan 42" and the agent routes to `scaffold_prepare_review`. Say "where did we leave off?" and it routes to `scaffold_orient`. Run `scaffold agents cursor` (or `windsurf`, `claude`) to generate platform-specific rules that wire this behavior into your IDE.
 
 **Composite tools** -- single calls that replace entire multi-step workflows:
 
@@ -130,6 +176,8 @@ You don't need to memorize tool names. AgentScaffold ships with **intent descrip
 | `scaffold_find_studies` | Searching study files by topic, tags, or outcome |
 | `scaffold_find_adrs` | Searching architecture decision records by topic or status |
 
+Use composite tools by default for common workflows; use granular tools when you need targeted control.
+
 **Granular tools** -- building blocks for custom queries:
 
 | Tool | What It Replaces |
@@ -193,9 +241,11 @@ The governance framework is domain-aware. Domain packs teach the adversarial rev
 | embedded | Memory constraints, real-time deadlines, OTA safety |
 | research | Reproducibility, statistical rigor, experiment protocol |
 
+This keeps governance strict where risk is high and lightweight where speed matters, without rewriting the core framework.
+
 ```bash
-scaffold domain add trading
-scaffold domain add webapp
+scaffold domains add trading
+scaffold domains add webapp
 ```
 
 ## Documentation

{agentscaffold-0.2.2 → agentscaffold-0.2.4}/docs/README.md

@@ -1,11 +1,35 @@
 # AgentScaffold Documentation
 
+## Choose Your Path
+
+AgentScaffold supports two interaction modes:
+
+- **Interactive Prompting Path (NL + MCP)**: You work in chat with your agent, and the
+  agent maps natural-language intent to governance and graph workflows.
+- **CLI / Automation Path**: You run explicit `scaffold` commands for deterministic
+  setup, verification, and unattended workflows.
+
+If you already used the governance framework before knowledge graph and MCP tooling,
+start here:
+
+- [Migrating Governance Workflow to NL + MCP](migrating-governance-to-nl-mcp.md)
+
+## Template Set Included by Init
+
+When you run `scaffold init`, AgentScaffold installs the full core planning template set:
+
+- `docs/ai/templates/plan_template.md` (feature)
+- `docs/ai/templates/plan_template_bugfix.md` (bugfix)
+- `docs/ai/templates/plan_template_refactor.md` (refactor)
+- plus spike and study templates for discovery and experiment workflows
+
 ## Guides
 
 | Document | Description |
 |----------|-------------|
 | [Getting Started](getting-started.md) | Installation, init, first plan, knowledge graph, review, execution |
 | [User Guide](user-guide.md) | Session workflow, knowledge graph, greenfield onboarding, review patterns, MCP tools |
+| [Migrating Governance to NL + MCP](migrating-governance-to-nl-mcp.md) | Command-heavy to conversational migration while preserving governance rigor |
 | [Configuration](configuration.md) | Full scaffold.yaml reference, gates, rigor presets |
 | [Domain Packs](domain-packs.md) | Available packs, installation, using multiple packs |
 | [Creating Domain Packs](creating-domain-packs.md) | Structure, manifest, prompts, standards |

{agentscaffold-0.2.2 → agentscaffold-0.2.4}/docs/configuration.md

@@ -224,6 +224,22 @@ Only applies when `profile: semi_autonomous` or `semi_autonomous.enabled: true`.
 
 ---
 
+## freshness
+
+Controls optional async graph freshness behavior for MCP tool calls.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| async_enabled | bool | true | Enable cheap request-path freshness checks and background refresh scheduling |
+| debounce_seconds | int | 120 | Minimum interval between refresh trigger attempts |
+| gate_strict | bool | false | Defer gate-transition calls when freshness is stale/unknown/refreshing |
+| background_queue_enabled | bool | true | Coalesce in-flight refresh triggers by setting a pending rerun |
+
+When enabled, MCP request handlers avoid synchronous re-indexing. They return freshness
+metadata and schedule eligible refreshes asynchronously.
+
+---
+
 ## How Gates Interact with Lifecycle
 
 ```

{agentscaffold-0.2.2 → agentscaffold-0.2.4}/docs/creating-domain-packs.md

@@ -17,7 +17,7 @@ my_domain/
     threat_model_my_domain.md.j2
 ```
 
-The pack directory name (e.g. `my_domain`) is the pack identifier used with `scaffold domain add my_domain`.
+The pack directory name (e.g. `my_domain`) is the pack identifier used with `scaffold domains add my_domain`.
 
 ## manifest.yaml Format
 
@@ -98,6 +98,25 @@ Use tables only for pass/fail checklists (short cell values).
 
 Reference the plan file, system architecture, and interface contracts. The agent will apply this prompt to the current plan.
 
+## Designing Prompts for Natural Invocation
+
+Most users will trigger your pack via conversational prompts, not explicit tool names.
+Write prompts so they are easy for an agent to route from natural language:
+
+- Use review titles and phrasing that match how humans ask (e.g., "quant architect review",
+  "product design review", "deployment safety review").
+- Include a short "When to use" phrase near the top that mirrors likely user requests.
+- Keep output instructions deterministic so routing confidence can stay high.
+
+Example natural invocations your prompt should support:
+
+- "Review this plan like a quant architect."
+- "Pressure-test this API plan for backward compatibility."
+- "Before implementation, run deployment safety checks."
+
+If the naming in `manifest.yaml` and the prompt header diverge too much from user language,
+agents are more likely to fall back to generic review behavior.
+
 ## Writing Standards
 
 Standards should be actionable with concrete examples:
@@ -146,7 +165,7 @@ For static content that works in any project, avoid template variables. If you n
 
    ```bash
    cd /path/to/test-project
-   scaffold domain add my_domain
+   scaffold domains add my_domain
    ```
 
 3. **Verify installation**: Check that files appear in `docs/ai/prompts/`, `docs/ai/standards/`, and `scaffold.yaml` was updated.

{agentscaffold-0.2.2 → agentscaffold-0.2.4}/docs/domain-packs.md

@@ -33,9 +33,13 @@ When you install a domain pack, its files are copied into your project and its s
 From your project root:
 
 ```bash
-scaffold domain add trading
+scaffold domains add trading
 ```
 
+Use `scaffold domains ...` commands for setup and configuration. For day-to-day usage in
+chat sessions, use natural-language prompts so the agent applies domain prompts through
+its governance/review flow.
+
 This will:
 
 1. Copy prompts to `docs/ai/prompts/`
@@ -46,7 +50,7 @@ This will:
 List available and installed packs:
 
 ```bash
-scaffold domain list
+scaffold domains list
 ```
 
 ## What Gets Added to Your Project
@@ -70,13 +74,25 @@ When you run `scaffold agents generate`, the generated AGENTS.md includes:
 
 The agent reads AGENTS.md and applies these rules during plan review and execution.
 
+## NL Prompt Patterns After Installation
+
+After installing packs, trigger domain behavior conversationally:
+
+- "Review plan 042 like a quant architect and challenge risk assumptions."
+- "Before implementation, run product design and accessibility scrutiny for this plan."
+- "Do a full adversarial review with both trading and webapp perspectives."
+- "Re-check the plan for domain-specific failure modes before we proceed."
+
+These prompts should route the agent into the same governance gates as explicit command
+flows while reducing interaction friction.
+
 ## Using Multiple Domain Packs
 
 You can install multiple packs. For example, a trading web app might use:
 
 ```bash
-scaffold domain add trading
-scaffold domain add webapp
+scaffold domains add trading
+scaffold domains add webapp
 ```
 
 Both packs' prompts and standards are merged. When a plan touches trading and UI:
@@ -85,6 +101,10 @@ Both packs' prompts and standards are merged. When a plan touches trading and UI
 - Both domains' standards apply
 - Approval gates from both packs are enforced
 
+Prompt example for dual-domain plans:
+
+> "Let's review this plan with quant architect and product design lenses before implementation."
+
 If prompts or standards from different packs conflict, the agent uses the most specific one for the plan's scope. For overlapping concerns, document your preference in the plan or in `docs/ai/standards/`.
 
 ## Creating Custom Domain Packs

{agentscaffold-0.2.2 → agentscaffold-0.2.4}/docs/getting-started.md

@@ -64,7 +64,7 @@ my-project/
   .cursor/rules.md       # Cursor-specific rules
   docs/
     ai/
-      templates/         # Plan, spike, study templates
+      templates/         # Plan templates (feature/bugfix/refactor), plus spike and study
       prompts/           # Devil's advocate, expansion, retrospective
       standards/         # Error handling, logging, testing
       state/             # workflow_state, learnings_tracker, plan_completion_log
@@ -80,6 +80,9 @@ my-project/
 - **AGENTS.md**: The agent reads this file to learn the plan lifecycle, gates, and collaboration protocol.
 - **scaffold.yaml**: Edit this to change rigor, gates, domains, or semi-autonomous settings.
 - **docs/ai/**: Source of truth for templates, prompts, and state. The agent references these paths.
+- **Plan templates included**: `docs/ai/templates/plan_template.md`,
+  `docs/ai/templates/plan_template_bugfix.md`, and
+  `docs/ai/templates/plan_template_refactor.md`.
 
 ## 4. Creating Your First Plan
 
@@ -177,7 +180,61 @@ This indexes your codebase into a local graph database (`.scaffold/graph.db`). F
 
 See the [Knowledge Graph section of the User Guide](user-guide.md#knowledge-graph-codebase-intelligence) for details on querying, MCP tools, and review integration.
 
-## 10. Next Steps
+### Optional: Enable Async Freshness for MCP Sessions
+
+If your repository is large and incremental indexing is slow, enable async freshness so MCP
+tool calls stay fast while graph refresh happens in the background.
+
+In `scaffold.yaml`:
+
+```yaml
+freshness:
+  async_enabled: true
+  debounce_seconds: 120
+  gate_strict: false
+  background_queue_enabled: true
+```
+
+Behavior:
+
+- Request path runs a cheap freshness check and returns immediately.
+- Eligible composite workflows schedule background `index --incremental` refreshes.
+- Tool metadata includes freshness state (`fresh`, `stale`, `unknown`, `refreshing`).
+- With `gate_strict: true`, lifecycle-gate transitions can defer until freshness is restored.
+
+## 10. Switch from Command-Heavy to NL + MCP
+
+If you previously drove every step with explicit structural commands, this is the point to
+switch to conversational prompting while preserving the same governance rigor.
+
+Readiness checklist:
+
+- [ ] MCP is configured for your platform (see [Platform Integration](platform-integration.md)).
+- [ ] You ran `scaffold index` at least once.
+- [ ] You regenerated rules after config/domain changes:
+  - `scaffold agents generate`
+  - `scaffold agents cursor` (or `scaffold agents windsurf` / `scaffold agents claude`)
+
+First 5 prompts to replace command-heavy orchestration:
+
+1. "Let's prepare to review plan 001 with evidence and challenge assumptions."
+2. "Before implementation, check whether plan 001 is stale and dependency-complete."
+3. "Compare plan 001 and plan 002 for overlap before we proceed."
+4. "Where did we leave off on plan 001 and what are blockers?"
+5. "Prepare retro context for plan 001 with prior findings and studies."
+
+Keep explicit commands for verification/operations:
+
+```bash
+scaffold index --incremental
+scaffold graph verify
+scaffold validate
+```
+
+For a full migration guide, see
+[Migrating Governance to NL + MCP](migrating-governance-to-nl-mcp.md).
+
+## 11. Next Steps
 
 - **Domain packs**: Add specialized reviews and standards. See [Domain Packs](domain-packs.md).
 - **Semi-autonomous mode**: Enable for CLI-triggered agents. See [Semi-Autonomous Guide](semi-autonomous-guide.md).

{agentscaffold-0.2.2 → agentscaffold-0.2.4}/docs/platform-integration.md

@@ -22,6 +22,48 @@ scaffold index                    # Build knowledge graph
 
 After this, your project has `AGENTS.md` at the root and `.scaffold/graph.db` with the indexed knowledge graph. The agent rules in `AGENTS.md` work immediately with any agent that reads project files.
 
+## Verify NL Intent Routing
+
+Before long sessions, run a quick smoke check in chat to confirm the agent is interpreting
+intent and routing to MCP workflows (or falling back cleanly when needed):
+
+1. "Let's prepare to review plan 042 with evidence."
+   - Expected behavior: review-prep/composite context workflow.
+2. "Where did we leave off and what are blockers?"
+   - Expected behavior: orientation/status workflow.
+3. "Show me the decision chain behind plan 042."
+   - Expected behavior: ADR/spike/study decision-context workflow.
+
+If routing is weak or MCP tools are unavailable:
+
+- Rebuild freshness: `scaffold index --incremental`
+- Regenerate rules: `scaffold agents generate` and platform-specific rules command
+- Continue in hybrid mode: explicit CLI commands for critical checks + NL orchestration
+
+This verification should take under two minutes and catches setup drift early.
+
+### Async Freshness (Recommended for Large Repos)
+
+If incremental indexing is heavy in your codebase, enable async freshness in `scaffold.yaml`.
+This keeps MCP request-path latency low by scheduling refresh in the background instead of
+blocking tool calls.
+
+```yaml
+freshness:
+  async_enabled: true
+  debounce_seconds: 120
+  gate_strict: false
+  background_queue_enabled: true
+```
+
+Operational notes:
+
+- Composite tools are eligible refresh triggers; refresh scheduling is debounced.
+- Single-flight locking prevents duplicate refresh jobs during parallel tool usage.
+- Tool responses include freshness metadata so the agent can disclose confidence.
+- For stricter governance, set `gate_strict: true` to defer gate transitions when freshness
+  is stale/unknown.
+
 ---
 
 ## Cursor
@@ -232,6 +274,9 @@ scaffold graph stats
 
 You can pipe CLI output into aider's context or use it to inform your prompts.
 
+For aider, the practical target mode is **hybrid**: conversational planning and governance
+prompts, with explicit CLI graph/review commands for context retrieval.
+
 ---
 
 ## Codex (OpenAI)

{agentscaffold-0.2.2 → agentscaffold-0.2.4}/docs/user-guide.md

@@ -14,6 +14,23 @@ Each phase has specific trigger phrases and expectations. The sections below det
 
 But first -- if you don't have any plans yet because you're starting a brand new project, read the Greenfield Onboarding section below.
 
+### Canonical Session Flow (NL + MCP Variant)
+
+If MCP is configured and indexed, you can run the same lifecycle with less command
+choreography. Instead of naming each tool, describe the outcome:
+
+| Phase | Command-Heavy Directive | NL + MCP Directive |
+|-------|-------------------------|--------------------|
+| Open | "Run review brief for plan 042" | "Let's prepare to review plan 042 with evidence." |
+| Assess | "Run staleness check" | "Is this plan stale after recent architecture changes?" |
+| Review | "Run critique + expansion + domain review" | "Pressure-test this plan and surface edge cases before implementation." |
+| Gaps Sweep | "Re-run all review outputs and list gaps" | "Do a full second-pass gap sweep across all review findings." |
+| Execute | "Proceed with step-by-step implementation" | "Begin implementation and follow plan steps in order." |
+| Close Out | "Run retro and update state files" | "Prepare retro context and complete close-out updates." |
+
+Use explicit commands when you need deterministic verification, reproducible outputs, or
+platform fallback.
+
 ---
 
 ## Greenfield Onboarding: Starting from Scratch
@@ -724,6 +741,35 @@ the flow has completed. lets review the findings
 
 ---
 
+## Migration Guide for Governance-First Users
+
+If you used AgentScaffold before knowledge graph/MCP integration, the safest shift is:
+
+1. **Hybrid first**: use NL prompts for orchestration, keep CLI verification explicit.
+2. **Verify behavior**: confirm the agent is routing to MCP context/review tools first.
+3. **Keep rigor fixed**: pre-reviews, gap sweep, validation, retro, and state updates stay mandatory.
+
+Phase-by-phase translation:
+
+| Old Structural Pattern | NL Prompt Pattern | Expected Tool Family |
+|------------------------|-------------------|----------------------|
+| "run review brief/challenges for plan X" | "prepare to review plan X with evidence" | composite review tools |
+| "run staleness check on plan X" | "is plan X stale after recent changes?" | staleness/validation tools |
+| "run impact on file/symbol Y" | "what is the blast radius of Y?" | impact/context tools |
+| "gather ADR/spike/study history" | "show the decision chain behind this plan" | decision context tools |
+| "run retro prep and findings pull" | "prepare retro context for this plan" | retro/studies tools |
+
+Fallback and override guardrails:
+
+- If MCP is unavailable, fall back to direct read/search and keep governance sequence intact.
+- If graph might be stale, run `scaffold index --incremental` before continuing.
+- Keep explicit validation commands (`scaffold validate`, `scaffold graph verify`) before completion.
+
+For a focused migration path, see
+[Migrating Governance to NL + MCP](migrating-governance-to-nl-mcp.md).
+
+---
+
 ## Knowledge Graph: Codebase Intelligence
 
 AgentScaffold can build a knowledge graph of your codebase using `scaffold index`. This graph powers several features: auto-enriched templates, graph-backed reviews, MCP tool integration, and a living Codebase Intelligence section in AGENTS.md.
@@ -761,6 +807,29 @@ scaffold index --incremental
 
 Incremental mode compares SHA-256 content hashes of files on disk against those stored in the graph. Only files that were added, modified, or deleted since the last index are processed. On a large codebase where only a handful of files changed, this is dramatically faster than a full re-index.
 
+### Async Freshness for MCP (Large-Repo UX)
+
+For large repositories, even incremental re-indexing can still take too long to run
+inline with tool calls. Async freshness mode separates freshness checks from refresh work:
+
+- Request path performs a cheap freshness oracle check.
+- Eligible composite tools schedule background incremental refreshes.
+- Debounce and single-flight locking avoid refresh storms.
+- Responses include freshness state so the agent can communicate confidence.
+
+Enable in `scaffold.yaml`:
+
+```yaml
+freshness:
+  async_enabled: true
+  debounce_seconds: 120
+  gate_strict: false
+  background_queue_enabled: true
+```
+
+If you need strict lifecycle control, set `gate_strict: true` so gate transitions defer
+when graph freshness is stale or unknown.
+
 The changeset output shows exactly what changed:
 ```
 Incremental index -- computing changeset...