@kamkom/awb-mcp 0.0.2 → 0.0.4

package/.ai/backlog.md

@@ -10,30 +10,30 @@ Stories and acceptance criteria derived from [.ai/prd.md](.ai/prd.md), grouped b
 
 **User story**
 
-- As a developer using VS Code with an MCP-capable agent/chat client  
-- I want to run the AWB MCP server as a stdio-based server so that I can use its tools from my editor without extra infrastructure  
+- As a developer using VS Code with an MCP-capable agent/chat client
+- I want to run the AWB MCP server as a stdio-based server so that I can use its tools from my editor without extra infrastructure
 
 **Acceptance criteria**
 
-- Given a Windows or macOS machine with Node.js and VS Code configured for MCP  
-- When I install the package (e.g. `npm i -g awb-mcp`) and add the server to my MCP settings with the command path  
-- Then the server starts over stdio, responds to MCP protocol messages, and exposes tools (e.g. list_tools returns AWB tools)  
+- Given a Windows or macOS machine with Node.js and VS Code configured for MCP
+- When I install the package (e.g. `npm i -g awb-mcp`) and add the server to my MCP settings with the command path
+- Then the server starts over stdio, responds to MCP protocol messages, and exposes tools (e.g. list_tools returns AWB tools)
 
 **Edge cases**
 
-- Linux: document as optional; no hard requirement to fix Linux-only issues in v0.1  
-- Invalid or missing `rootPath`: server returns clear error, does not crash  
-- Server receives malformed or unexpected JSON: responds with protocol error, does not exit ungracefully  
+- Linux: document as optional; no hard requirement to fix Linux-only issues in v0.1
+- Invalid or missing `rootPath`: server returns clear error, does not crash
+- Server receives malformed or unexpected JSON: responds with protocol error, does not exit ungracefully
 
 **Technical considerations**
 
-- Use `@modelcontextprotocol/sdk` StdioServerTransport; single executable entrypoint (e.g. `awb-mcp` or `npx awb-mcp`)  
-- No network listener; stdio only  
-- Package `bin` in package.json so `awb-mcp` is on PATH after global install  
+- Use `@modelcontextprotocol/sdk` StdioServerTransport; single executable entrypoint (e.g. `awb-mcp` or `npx awb-mcp`)
+- No network listener; stdio only
+- Package `bin` in package.json so `awb-mcp` is on PATH after global install
 
 **Design notes**
 
-- Keep VS Code MCP config minimal: only the command (e.g. `awb-mcp` or `npx awb-mcp`). No required env vars or args for basic use  
+- Keep VS Code MCP config minimal: only the command (e.g. `awb-mcp` or `npx awb-mcp`). No required env vars or args for basic use
 
 ---
 
@@ -41,39 +41,39 @@ Stories and acceptance criteria derived from [.ai/prd.md](.ai/prd.md), grouped b
 
 **User story**
 
-- As a user in an agentic workflow  
-- I want to call `awb.plan_bootstrap` with a repo root and options so that I get a clear, deterministic plan of file operations (create/update/skip) with full file contents and warnings for existing files  
+- As a user in an agentic workflow
+- I want to call `awb.plan_bootstrap` with a repo root and options so that I get a clear, deterministic plan of file operations (create/update/skip) with full file contents and warnings for existing files
 
 **Acceptance criteria**
 
-- Given a valid `rootPath` (existing directory) and optional `options` (mode, includeReadmeProposal, overwritePolicy, files allowlist)  
-- When I call the tool `awb.plan_bootstrap` with those inputs  
-- Then I receive a response containing: a unique `planId`; an `operations[]` array with for each path: `path`, `action` (CREATE | UPDATE_MANAGED | SKIP), `content` when action is CREATE or UPDATE_MANAGED, `reason` (especially for SKIP), and `warnings[]`; optional `repoHints` and `readmeProposal` when requested  
+- Given a valid `rootPath` (existing directory) and optional `options` (mode, includeReadmeProposal, overwritePolicy, files allowlist)
+- When I call the tool `awb.plan_bootstrap` with those inputs
+- Then I receive a response containing: a unique `planId`; an `operations[]` array with for each path: `path`, `action` (CREATE | UPDATE_MANAGED | SKIP), `content` when action is CREATE or UPDATE_MANAGED, `reason` (especially for SKIP), and `warnings[]`; optional `repoHints` and `readmeProposal` when requested
 
-- Given a path that does not exist on disk  
-- When the plan is computed  
-- Then that path has action CREATE and includes full static template content  
+- Given a path that does not exist on disk
+- When the plan is computed
+- Then that path has action CREATE and includes full static template content
 
-- Given a path that exists and has no AWB managed block and overwritePolicy is not "overwrite"  
-- When the plan is computed  
-- Then that path has action SKIP, a reason, and a warning that the file exists and is not being overwritten  
+- Given a path that exists and has no AWB managed block and overwritePolicy is not "overwrite"
+- When the plan is computed
+- Then that path has action SKIP, a reason, and a warning that the file exists and is not being overwritten
 
 **Edge cases**
 
-- `rootPath` is a file or non-existent: return clear error, no plan  
-- `files` allowlist: only those paths appear in operations; others are omitted  
-- Empty repo (no existing scaffold): all scaffold paths are CREATE  
-- overwritePolicy `"skip"`: existing files always SKIP (even if they contain a managed block). `"managed-only"`: SKIP unless file has AWB managed block (then UPDATE_MANAGED)  
+- `rootPath` is a file or non-existent: return clear error, no plan
+- `files` allowlist: only those paths appear in operations; others are omitted
+- Empty repo (no existing scaffold): all scaffold paths are CREATE
+- overwritePolicy `"skip"`: existing files always SKIP (even if they contain a managed block). `"managed-only"`: SKIP unless file has AWB managed block (then UPDATE_MANAGED)
 
 **Technical considerations**
 
-- planId: UUID or timestamp-based unique string; same inputs produce same plan content (deterministic)  
-- Read only: directory listing and file existence (and optionally small config files for hints). No writes in plan  
-- Input schema: validate rootPath (string), options optional with zod or equivalent  
+- planId: UUID or timestamp-based unique string; same inputs produce same plan content (deterministic)
+- Read only: directory listing and file existence (and optionally small config files for hints). No writes in plan
+- Input schema: validate rootPath (string), options optional with zod or equivalent
 
 **Design notes**
 
-- Static mode default: all templates are prefilled content from server bundle. No LLM calls in server  
+- Static mode default: all templates are prefilled content from server bundle. No LLM calls in server
 
 ---
 
@@ -81,38 +81,38 @@ Stories and acceptance criteria derived from [.ai/prd.md](.ai/prd.md), grouped b
 
 **User story**
 
-- As a user who has reviewed a bootstrap plan  
-- I want to call `awb.apply_bootstrap` with the planId and operations so that only approved changes are written to disk using atomic writes and explicit conflict handling  
+- As a user who has reviewed a bootstrap plan
+- I want to call `awb.apply_bootstrap` with the planId and operations so that only approved changes are written to disk using atomic writes and explicit conflict handling
 
 **Acceptance criteria**
 
-- Given a valid `rootPath`, the `planId` from a prior `plan_bootstrap` call, and the same `operations[]` (or server-validated subset)  
-- When I call `awb.apply_bootstrap` without dryRun  
-- Then each CREATE/UPDATE_MANAGED operation is written to disk; each SKIP is not written; the response includes `results[]` with per-path `status` (WRITTEN | SKIPPED | FAILED) and `details`  
+- Given a valid `rootPath`, the `planId` from a prior `plan_bootstrap` call, and the same `operations[]` (or server-validated subset)
+- When I call `awb.apply_bootstrap` without dryRun
+- Then each CREATE/UPDATE_MANAGED operation is written to disk; each SKIP is not written; the response includes `results[]` with per-path `status` (WRITTEN | SKIPPED | FAILED) and `details`
 
-- Given applyOptions.dryRun is true  
-- When I call `awb.apply_bootstrap`  
-- Then no files are modified and the response describes what would have been done (e.g. same result structure with WRITTEN/SKIPPED/FAILED as if applied)  
+- Given applyOptions.dryRun is true
+- When I call `awb.apply_bootstrap`
+- Then no files are modified and the response describes what would have been done (e.g. same result structure with WRITTEN/SKIPPED/FAILED as if applied)
 
-- Given writeMode is "atomic" (default)  
-- When a file is written  
-- Then content is written to a temp file in the same directory and then renamed into place so that partial writes are not visible  
+- Given writeMode is "atomic" (default)
+- When a file is written
+- Then content is written to a temp file in the same directory and then renamed into place so that partial writes are not visible
 
 **Edge cases**
 
-- planId or operations do not match a recent plan: server may validate and return FAILED for mismatches if failOnConflict is true  
-- Disk full or permission error: that path returns status FAILED with details; other paths still attempted where possible  
-- apply_bootstrap called with operations from a different rootPath: server validates and rejects or marks FAILED  
+- planId or operations do not match a recent plan: server may validate and return FAILED for mismatches if failOnConflict is true
+- Disk full or permission error: that path returns status FAILED with details; other paths still attempted where possible
+- apply_bootstrap called with operations from a different rootPath: server validates and rejects or marks FAILED
 
 **Technical considerations**
 
-- Atomic write: write to `*.tmp` (or similar) in same directory, fs.rename to final path  
-- Idempotency: applying the same plan twice with same overwrite policy should yield same outcome (second run no unexpected changes)  
-- applyOptions: dryRun, writeMode "atomic", failOnConflict (default true)  
+- Atomic write: write to `*.tmp` (or similar) in same directory, fs.rename to final path
+- Idempotency: applying the same plan twice with same overwrite policy should yield same outcome (second run no unexpected changes)
+- applyOptions: dryRun, writeMode "atomic", failOnConflict (default true)
 
 **Design notes**
 
-- Server does not re-read disk to “re-plan”; it applies the operations as given, enforcing overwrite policy per operation  
+- Server does not re-read disk to “re-plan”; it applies the operations as given, enforcing overwrite policy per operation
 
 ---
 
@@ -120,40 +120,40 @@ Stories and acceptance criteria derived from [.ai/prd.md](.ai/prd.md), grouped b
 
 **User story**
 
-- As a user running bootstrap in a repo that may already have some files  
-- I want the server to never overwrite my content unless a file is under AWB management or I explicitly allow overwrite so that I do not lose work  
+- As a user running bootstrap in a repo that may already have some files
+- I want the server to never overwrite my content unless a file is under AWB management or I explicitly allow overwrite so that I do not lose work
 
 **Acceptance criteria**
 
-- Given a target path where the file does not exist  
-- When the plan is computed and applied  
-- Then the action is CREATE and the file is created  
+- Given a target path where the file does not exist
+- When the plan is computed and applied
+- Then the action is CREATE and the file is created
 
-- Given a target path where the file exists and does not contain the AWB managed block marker  
-- When overwritePolicy is "skip" or "managed-only" (default)  
-- Then the action is SKIP, reason and warnings are set, and the file is not modified on apply  
+- Given a target path where the file exists and does not contain the AWB managed block marker
+- When overwritePolicy is "skip" or "managed-only" (default)
+- Then the action is SKIP, reason and warnings are set, and the file is not modified on apply
 
-- Given a target path where the file exists and contains the AWB managed block marker  
-- When overwritePolicy is "managed-only" (default)  
-- Then the action is UPDATE_MANAGED, content is the new managed block content, and on apply only the managed section is updated (or full file replace per implementation)  
+- Given a target path where the file exists and contains the AWB managed block marker
+- When overwritePolicy is "managed-only" (default)
+- Then the action is UPDATE_MANAGED, content is the new managed block content, and on apply only the managed section is updated (or full file replace per implementation)
 
-- Given the user passes overwrite: true for a specific file (or overwritePolicy "overwrite")  
-- When the plan is computed and applied  
-- Then that path can be CREATE/UPDATE and existing content may be replaced; user has explicitly opted in  
+- Given the user passes overwrite: true for a specific file (or overwritePolicy "overwrite")
+- When the plan is computed and applied
+- Then that path can be CREATE/UPDATE and existing content may be replaced; user has explicitly opted in
 
 **Edge cases**
 
-- Managed block marker missing or malformed: treat as unmanaged, SKIP unless overwrite  
-- Partial file (e.g. only start marker): define behavior (e.g. SKIP or treat as managed); document  
+- Managed block marker missing or malformed: treat as unmanaged, SKIP unless overwrite
+- Partial file (e.g. only start marker): define behavior (e.g. SKIP or treat as managed); document
 
 **Technical considerations**
 
-- Define a single, documented AWB managed block format (e.g. `<!-- AWB MANAGED BEGIN -->` … `<!-- AWB MANAGED END -->` or similar)  
-- plan_bootstrap decides CREATE | UPDATE_MANAGED | SKIP per path based on existence and overwrite policy; apply_bootstrap enforces the same policy  
+- Define a single, documented AWB managed block format (e.g. `<!-- AWB MANAGED BEGIN -->` … `<!-- AWB MANAGED END -->` or similar)
+- plan_bootstrap decides CREATE | UPDATE_MANAGED | SKIP per path based on existence and overwrite policy; apply_bootstrap enforces the same policy
 
 **Design notes**
 
-- Safe-by-default: “plan first, then apply” with clear SKIP behavior and no blind overwrites  
+- Safe-by-default: “plan first, then apply” with clear SKIP behavior and no blind overwrites
 
 ---
 
@@ -161,118 +161,36 @@ Stories and acceptance criteria derived from [.ai/prd.md](.ai/prd.md), grouped b
 
 **User story**
 
-- As a user bootstrapping a repo for agentic workflows  
-- I want the server to generate a fixed set of high-quality, generic template files so that my repo has a standard structure for instructions, prompts, and agents without me creating them by hand  
+- As a user bootstrapping a repo for agentic workflows
+- I want the server to generate a fixed set of high-quality, generic template files so that my repo has a standard structure for instructions, prompts, and agents without me creating them by hand
 
 **Acceptance criteria**
 
-- Given a successful `plan_bootstrap` in static mode with no files allowlist (or allowlist including the baseline paths)  
-- When the plan is generated  
-- Then operations include the full baseline tree: `.github/copilot-instructions.md`, `.github/instructions/general.instructions.md`, `.github/instructions/testing.instructions.md`, `.github/prompts/readme.prompt.md`, `.github/prompts/onboarding.prompt.md`, `.github/prompts/change-summary.prompt.md`, `.github/agents/architect.agent.md`, `.github/agents/implementer.agent.md`, `.github/agents/reviewer.agent.md`, `AGENTS.md`  
+- Given a successful `plan_bootstrap` in static mode with no files allowlist (or allowlist including the baseline paths)
+- When the plan is generated
+- Then operations include the full baseline tree: `.github/copilot-instructions.md`, `.github/instructions/general.instructions.md`, `.github/instructions/testing.instructions.md`, `.github/prompts/readme.prompt.md`, `.github/prompts/onboarding.prompt.md`, `.github/prompts/change-summary.prompt.md`, `.github/agents/architect.agent.md`, `.github/agents/implementer.agent.md`, `.github/agents/reviewer.agent.md`, `AGENTS.md`
 
-- Given the template content returned in the plan  
-- When I read it  
-- Then it is generic, high-signal, and safe: emphasizes “don’t guess,” “prefer repo scripts,” “write tests,” “avoid destructive commands”  
-- And placeholders (e.g. `{{packageManager}}`, `{{testCommand}}`) are minimal and optional; may be left as defaults in v0.1  
+- Given the template content returned in the plan
+- When I read it
+- Then it is generic, high-signal, and safe: emphasizes “don’t guess,” “prefer repo scripts,” “write tests,” “avoid destructive commands”
+- And placeholders (e.g. `{{packageManager}}`, `{{testCommand}}`) are minimal and optional; may be left as defaults in v0.1
 
 **Edge cases**
 
-- `files` allowlist provided: only listed paths that belong to the baseline appear in operations  
-- Paths outside repo root (e.g. `..` in path): server rejects or normalizes  
+- `files` allowlist provided: only listed paths that belong to the baseline appear in operations
+- Paths outside repo root (e.g. `..` in path): server rejects or normalizes
 
 **Technical considerations**
 
-- Templates shipped as static files in the server package (e.g. in a `templates/` directory); no runtime fetch  
-- Use path.join(rootPath, ...) for all paths; normalize and reject paths not under rootPath  
+- Templates shipped as static files in the server package (e.g. in a `templates/` directory); no runtime fetch
+- Use path.join(rootPath, ...) for all paths; normalize and reject paths not under rootPath
 
 **Design notes**
 
-- Templates work for any repo/stack; no stack-specific logic required in v0.1  
+- Templates work for any repo/stack; no stack-specific logic required in v0.1
 
 ---
 
-### Story 6: Safety — no network, no shell, minimal reads, atomic writes
-
-**User story**
-
-- As a user running the AWB MCP server  
-- I want it to never perform network calls, shell execution, or broad filesystem reads so that I can trust it in sensitive or offline environments  
-
-**Acceptance criteria**
-
-- Given the server is running  
-- When any tool is invoked  
-- Then the server does not open outbound network connections or spawn shell/child processes  
-
-- Given plan_bootstrap or apply_bootstrap is called  
-- When the server needs to check files  
-- Then it only checks existence of target paths and, if needed, reads small config files (e.g. package.json) for hints; it does not read arbitrary or sensitive paths beyond what is documented  
-
-- Given apply_bootstrap writes a file  
-- When writeMode is atomic  
-- Then content is written to a temp file and then renamed; no partial content is visible at the final path on failure  
-
-- Given a file already exists and policy says SKIP  
-- When apply_bootstrap runs  
-- Then the user sees clear warnings in the plan and the apply result reflects SKIPPED with a reason  
-
-**Edge cases**
-
-- Symlinks: document whether we follow or reject; prefer not following symlinks outside rootPath  
-- Very long paths or huge files: avoid reading large files; existence check only where sufficient  
-
-**Technical considerations**
-
-- No require('child_process') or fetch/axios; no external HTTP  
-- Atomic write: temp file in same directory as target, then rename  
-- Explicit allowlist of files that may be read for hints (e.g. package.json, pyproject.toml) in v0.2  
-
-**Design notes**
-
-- Security section of PRD is non-negotiable for MVP; tests or checklist can enforce “no network, no shell”  
-
----
-
-### Story 7: Early deployment and validation — works on other computers
-
-**User story**
-
-- As a maintainer or a user trying the package on a clean machine  
-- I want a clear packaging, install, and validation flow so that we can confirm the server runs on other computers (Windows and macOS) and works with VS Code MCP  
-
-**Acceptance criteria**
-
-- Given the project is built and published (e.g. to npm as `awb-mcp` or installed from tarball)  
-- When another user on a clean Windows or macOS machine runs `npm i -g awb-mcp` (or equivalent)  
-- Then the install completes and the `awb-mcp` (or documented) command is on PATH  
-
-- Given the server is installed globally  
-- When the user adds the server to VS Code MCP settings (e.g. in settings.json or Cursor MCP config) with only the command path  
-- Then VS Code/Cursor can start the server over stdio and list tools  
-
-- Given the server is running in VS Code  
-- When the user (or a script) invokes `awb.plan_bootstrap` with a valid repo root  
-- Then the tool returns a valid plan (planId, operations array, no crash)  
-
-- Given a release checklist exists (in repo or docs)  
-- When preparing a release  
-- Then the checklist includes: build, pack or publish, install on clean Windows, install on clean macOS, configure VS Code MCP, run smoke test (plan_bootstrap + optional apply_bootstrap in a temp dir)  
-
-**Edge cases**
-
-- Node version: document minimum (e.g. Node 18+); package.json engines optional  
-- npx vs global install: both documented; smoke test covers at least one  
-
-**Technical considerations**
-
-- package.json: `bin` entry for the executable; `main` or type module and entrypoint that runs the MCP server  
-- Build step that produces runnable code (e.g. tsc + node, or tsx in bin); ensure dependencies are bundled or declared so install is self-contained  
-- Optional: simple smoke script (e.g. node -e "call MCP list_tools") or doc that says “run plan_bootstrap from client”  
-
-**Design notes**
-
-- Early deployment is crucial: first milestone should include “works on another machine” validation; checklist prevents regressions  
-
 ---
 
 ## v0.2 — Repo hints and README proposal
@@ -281,37 +199,37 @@ Stories and acceptance criteria derived from [.ai/prd.md](.ai/prd.md), grouped b
 
 **User story**
 
-- As a user with an existing repo (e.g. with package.json or pyproject.toml)  
-- I want the server to run lightweight heuristics to detect hints (e.g. package manager, test command) so that bootstrap templates can be filled with sensible defaults without deep stack detection  
+- As a user with an existing repo (e.g. with package.json or pyproject.toml)
+- I want the server to run lightweight heuristics to detect hints (e.g. package manager, test command) so that bootstrap templates can be filled with sensible defaults without deep stack detection
 
 **Acceptance criteria**
 
-- Given a repo root that contains one or more of: package.json, lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml), pyproject.toml  
-- When `awb.detect_repo_hints` (or plan_bootstrap with hint detection) runs  
-- Then the result includes a small `repoHints` object with fields such as preferred package manager, test command placeholder, or similar; no heavy or framework-specific detection  
+- Given a repo root that contains one or more of: package.json, lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml), pyproject.toml
+- When `awb.detect_repo_hints` (or plan_bootstrap with hint detection) runs
+- Then the result includes a small `repoHints` object with fields such as preferred package manager, test command placeholder, or similar; no heavy or framework-specific detection
 
-- Given repoHints are available  
-- When plan_bootstrap returns template content  
-- Then optional placeholders (e.g. `{{packageManager}}`, `{{testCommand}}`) are replaced with hint values where possible; otherwise left as safe defaults  
+- Given repoHints are available
+- When plan_bootstrap returns template content
+- Then optional placeholders (e.g. `{{packageManager}}`, `{{testCommand}}`) are replaced with hint values where possible; otherwise left as safe defaults
 
-- Given a repo with no known config files  
-- When detect runs  
-- Then repoHints is empty or has defaults; no error  
+- Given a repo with no known config files
+- When detect runs
+- Then repoHints is empty or has defaults; no error
 
 **Edge cases**
 
-- Multiple lockfiles: define precedence (e.g. pnpm > yarn > npm) and document  
-- Malformed package.json: do not throw; return partial or empty hints  
-- Must not become a “stack detection framework”: only a small, fixed set of heuristics  
+- Multiple lockfiles: define precedence (e.g. pnpm > yarn > npm) and document
+- Malformed package.json: do not throw; return partial or empty hints
+- Must not become a “stack detection framework”: only a small, fixed set of heuristics
 
 **Technical considerations**
 
-- detect_repo_hints: read only package.json, pyproject.toml, lockfile presence; no install or parse of dependencies  
-- Keep logic in one place; call from plan_bootstrap when options request hints  
+- detect_repo_hints: read only package.json, pyproject.toml, lockfile presence; no install or parse of dependencies
+- Keep logic in one place; call from plan_bootstrap when options request hints
 
 **Design notes**
 
-- v0.2 scope: minimal placeholders; avoid scope creep into full stack detection  
+- v0.2 scope: minimal placeholders; avoid scope creep into full stack detection
 
 ---
 
@@ -319,37 +237,37 @@ Stories and acceptance criteria derived from [.ai/prd.md](.ai/prd.md), grouped b
 
 **User story**
 
-- As a user who has an existing README.md  
-- I want the server to optionally suggest README content or a patch (e.g. README.agentic.md or a patch output) so that I can choose whether to integrate it without ever overwriting README.md by default  
+- As a user who has an existing README.md
+- I want the server to optionally suggest README content or a patch (e.g. README.agentic.md or a patch output) so that I can choose whether to integrate it without ever overwriting README.md by default
 
 **Acceptance criteria**
 
-- Given plan_bootstrap is called with includeReadmeProposal: false (default)  
-- When the plan is returned  
-- Then no readmeProposal field or README-related write is included; README.md is never in operations as an overwrite  
+- Given plan_bootstrap is called with includeReadmeProposal: false (default)
+- When the plan is returned
+- Then no readmeProposal field or README-related write is included; README.md is never in operations as an overwrite
 
-- Given plan_bootstrap is called with includeReadmeProposal: true  
-- When the plan is returned  
-- Then the response includes a readmeProposal (e.g. suggested content or a separate file path like README.agentic.md or a patch); README.md is still not in operations unless user explicitly opts in elsewhere  
-- And the client (LLM/user) decides whether to apply any README changes  
+- Given plan_bootstrap is called with includeReadmeProposal: true
+- When the plan is returned
+- Then the response includes a readmeProposal (e.g. suggested content or a separate file path like README.agentic.md or a patch); README.md is still not in operations unless user explicitly opts in elsewhere
+- And the client (LLM/user) decides whether to apply any README changes
 
-- Given the server suggests README content  
-- When the suggestion is returned  
-- Then it is clearly a proposal (e.g. “suggested addition” or separate file); default behavior never modifies README.md  
+- Given the server suggests README content
+- When the suggestion is returned
+- Then it is clearly a proposal (e.g. “suggested addition” or separate file); default behavior never modifies README.md
 
 **Edge cases**
 
-- No README.md exists: readmeProposal can still suggest initial README content  
-- Very long README: server may suggest a patch or appendix only; avoid loading huge files unnecessarily  
+- No README.md exists: readmeProposal can still suggest initial README content
+- Very long README: server may suggest a patch or appendix only; avoid loading huge files unnecessarily
 
 **Technical considerations**
 
-- readmeProposal: string content or { path, content } for a separate file; optional patch format  
-- If README.md is ever in operations, it is only when overwritePolicy or explicit overwrite is set and documented  
+- readmeProposal: string content or { path, content } for a separate file; optional patch format
+- If README.md is ever in operations, it is only when overwritePolicy or explicit overwrite is set and documented
 
 **Design notes**
 
-- Narrow MVP: README handling is optional and safe-by-default; no automatic overwrite  
+- Narrow MVP: README handling is optional and safe-by-default; no automatic overwrite
 
 ---
 
@@ -359,33 +277,33 @@ Stories and acceptance criteria derived from [.ai/prd.md](.ai/prd.md), grouped b
 
 **User story**
 
-- As a user who wants AI-generated bootstrap content tailored to my repo  
-- I want the server to support a “prompt” mode where it returns prompts and minimal skeleton files so that my client LLM (e.g. Copilot) can refine content before I apply it, without the server calling any external LLM  
+- As a user who wants AI-generated bootstrap content tailored to my repo
+- I want the server to support a “prompt” mode where it returns prompts and minimal skeleton files so that my client LLM (e.g. Copilot) can refine content before I apply it, without the server calling any external LLM
 
 **Acceptance criteria**
 
-- Given plan_bootstrap is called with mode: "prompt"  
-- When the plan is computed  
-- Then the server returns either (a) prompts plus minimal skeleton file content, or (b) static templates with a note that the client LLM may refine them before apply  
-- And the server does not call any third-party LLM API; any generation is done by the client using the user’s model  
+- Given plan_bootstrap is called with mode: "prompt"
+- When the plan is computed
+- Then the server returns either (a) prompts plus minimal skeleton file content, or (b) static templates with a note that the client LLM may refine them before apply
+- And the server does not call any third-party LLM API; any generation is done by the client using the user’s model
 
-- Given the client has refined or generated content  
-- When the user calls apply_bootstrap with the modified plan/operations  
-- Then the server applies the provided content with the same overwrite and atomic-write rules as static mode  
+- Given the client has refined or generated content
+- When the user calls apply_bootstrap with the modified plan/operations
+- Then the server applies the provided content with the same overwrite and atomic-write rules as static mode
 
 **Edge cases**
 
-- mode "prompt" with no client LLM: user can still apply skeletons as-is  
-- Mixed mode (some static, some prompt): v0.3 can define per-file or global; keep simple  
+- mode "prompt" with no client LLM: user can still apply skeletons as-is
+- Mixed mode (some static, some prompt): v0.3 can define per-file or global; keep simple
 
 **Technical considerations**
 
-- No fetch to OpenAI/Anthropic/etc. in server; prompts are strings returned to client  
-- Client is responsible for calling LLM and passing back refined content in the plan/operations  
+- No fetch to OpenAI/Anthropic/etc. in server; prompts are strings returned to client
+- Client is responsible for calling LLM and passing back refined content in the plan/operations
 
 **Design notes**
 
-- MVP: prompt mode is optional; static mode remains default and primary  
+- MVP: prompt mode is optional; static mode remains default and primary
 
 ---
 
@@ -393,43 +311,43 @@ Stories and acceptance criteria derived from [.ai/prd.md](.ai/prd.md), grouped b
 
 **User story**
 
-- As a user or client LLM  
-- I want to discover bootstrap-related prompts and read template resources via MCP so that I can run guided workflows (e.g. “bootstrap_agentic_repo”) or preview templates without calling tools  
+- As a user or client LLM
+- I want to discover bootstrap-related prompts and read template resources via MCP so that I can run guided workflows (e.g. “bootstrap_agentic_repo”) or preview templates without calling tools
 
 **Acceptance criteria**
 
-- Given the server supports optional Prompts  
-- When the client lists prompts  
-- Then at least one prompt is available (e.g. bootstrap_agentic_repo) that instructs the client to call plan_bootstrap, review output, then call apply_bootstrap  
+- Given the server supports optional Prompts
+- When the client lists prompts
+- Then at least one prompt is available (e.g. bootstrap_agentic_repo) that instructs the client to call plan_bootstrap, review output, then call apply_bootstrap
 
-- Given the server supports optional Resources  
-- When the client requests a resource URI (e.g. awb://templates/copilot-instructions.md or awb://templates/AGENTS.md)  
-- Then the server returns read-only template content for that path  
+- Given the server supports optional Resources
+- When the client requests a resource URI (e.g. awb://templates/copilot-instructions.md or awb://templates/AGENTS.md)
+- Then the server returns read-only template content for that path
 
-- Given tools already return full template content in plan_bootstrap  
-- When implementing resources  
-- Then resources are optional; same content can be exposed via tools only  
+- Given tools already return full template content in plan_bootstrap
+- When implementing resources
+- Then resources are optional; same content can be exposed via tools only
 
 **Edge cases**
 
-- Client does not support prompts/resources: server still works with tools only  
-- Unknown resource URI: return 404 or equivalent error  
+- Client does not support prompts/resources: server still works with tools only
+- Unknown resource URI: return 404 or equivalent error
 
 **Technical considerations**
 
-- MCP Prompts: register with the SDK; bootstrap_agentic_repo and optionally draft_readme_patch  
-- MCP Resources: register template URIs; resolve to static files from package  
+- MCP Prompts: register with the SDK; bootstrap_agentic_repo and optionally draft_readme_patch
+- MCP Resources: register template URIs; resolve to static files from package
 
 **Design notes**
 
-- v0.3 “only if needed”; if ship is faster without resources, tools-only is acceptable  
+- v0.3 “only if needed”; if ship is faster without resources, tools-only is acceptable
 
 ---
 
 ## Coverage and consistency
 
-- All PRD MVP goals and tool contracts (plan_bootstrap, apply_bootstrap, overwrite rules, baseline scaffold, safety, distribution) are covered by v0.1 stories.  
-- v0.2 covers detect_repo_hints and README proposal.  
-- v0.3 covers prompt mode and optional prompts/resources.  
-- Early deployment (Story 7) is part of v0.1 so that “works on other computers” is validated before or with the first usable release.  
-- Acceptance criteria are written in Given/When/Then form and are testable (manual or automated).  
+- All PRD MVP goals and tool contracts (plan_bootstrap, apply_bootstrap, overwrite rules, baseline scaffold, safety, distribution) are covered by v0.1 stories.
+- v0.2 covers detect_repo_hints and README proposal.
+- v0.3 covers prompt mode and optional prompts/resources.
+- Early deployment (Story 7) is part of v0.1 so that “works on other computers” is validated before or with the first usable release.
+- Acceptance criteria are written in Given/When/Then form and are testable (manual or automated).

package/AGENTS.md

@@ -0,0 +1,3 @@
+# Agents
+
+This repo uses agentic workflows. Prefer repo scripts, write tests, and avoid destructive commands.