ma-agents 3.4.8 → 3.5.0

package/_bmad-output/implementation-artifacts/done/16-1-repository-layout-wizard.md

@@ -0,0 +1,223 @@
+# Story 16.1: Repository Layout Wizard
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want the installer to ask where the knowledgebase and sprint management are managed during installation,
+So that the project layout is configured correctly for multi-repo environments.
+
+## Acceptance Criteria
+
+1. When the user runs `npx ma-agents install`, the wizard asks "Where is your knowledgebase managed?" with options: Current repository (default), Local path, Remote git repository (FR111)
+2. The wizard asks "Where is your sprint management managed?" with the same options (FR112)
+3. When the user selects "Remote git repository", the wizard asks for the git URL and local destination path for cloning. If the destination already exists and is a directory, it displays its contents summary and asks the user to confirm. If it exists but is a file, it warns and re-prompts (FR113)
+4. When the user selects "Remote git repository" and the destination does not exist, it clones the repository to that path using `execFileSync` (not `execSync`) to prevent command injection (FR114)
+5. When the user selects "Local path", the wizard validates the path exists and is a directory. If it does not exist, it alerts the user and asks to confirm or correct. If confirmed, logs a warning that the path must exist before agents run (FR115)
+6. When the user selects "Current repository" for both concerns, no additional configuration is needed — single-repo mode preserved (FR116)
+7. In `--yes` flag (CI/CD mode), the wizard checks env vars `MA_KNOWLEDGEBASE_PATH` and `MA_SPRINT_PATH`. If set, uses those paths (mode=local). If not set, defaults to "Current repository" (mode=same). Multi-repo is configurable headlessly via env vars (FR127 integration)
+8. Git clone uses `execFileSync('git', ['clone', gitUrl, destPath])` with `{ timeout: 120000, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } }` for space-safety, injection prevention, and hang protection
+9. Empty/whitespace-only inputs for git URL or destination path are rejected with re-prompt
+10. If a clone fails, any partially-created destination directory is cleaned up before offering retry. If user skips, the concern falls back to `same` mode with a warning logged
+
+## Tasks / Subtasks
+
+- [x] Task 1: Add `collectRepoLayout()` function to `bin/cli.js` (AC: #1, #2, #6, #7)
+  - [x] 1.1 Create `collectRepoLayout(flags)` async function in `bin/cli.js`
+  - [x] 1.2 Implement the knowledgebase prompt using `prompts` library (type: `'select'`, choices as `{ title, value }` objects — matching existing wizard patterns)
+  - [x] 1.3 Implement the sprint management prompt with same choices
+  - [x] 1.4 Return layout object: `{ knowledgebase: { mode, path, gitUrl? }, sprintManagement: { mode, path, gitUrl? } }`
+  - [x] 1.5 When mode is `same`, set `path: '.'`
+  - [x] 1.6 In `--yes` mode: check `process.env.MA_KNOWLEDGEBASE_PATH` and `process.env.MA_SPRINT_PATH`. If set, use `{ mode: 'local', path: path.resolve(envValue) }`. If not set, use `{ mode: 'same', path: '.' }`
+  - [x] 1.7 If both concerns resolve to the same external path, log info: "Both concerns point to same external repository"
+
+- [x] Task 2: Implement "Local path" flow (AC: #5, #9)
+  - [x] 2.1 Prompt user for local path string; reject empty/whitespace-only input with re-prompt
+  - [x] 2.2 Resolve to absolute path via `path.resolve(process.cwd(), localPath)`
+  - [x] 2.3 Check `fs.existsSync(resolved)`: if exists, verify `fs.statSync(resolved).isDirectory()` — if it's a file, warn and re-prompt
+  - [x] 2.4 If path does not exist: display warning with `chalk.yellow()`, ask user to confirm or provide corrected path
+  - [x] 2.5 If confirmed non-existent: store resolved path, log warning that path must exist before agents run
+  - [x] 2.6 If not confirmed, re-prompt for the path (loop)
+  - [x] 2.7 Warn if resolved path is inside the current repo (`resolved.startsWith(process.cwd())`) — nested repos cause git confusion
+
+- [x] Task 3: Implement "Remote git repository" flow (AC: #3, #4, #8, #9, #10)
+  - [x] 3.1 Prompt user for git URL string; reject empty/whitespace-only input with re-prompt
+  - [x] 3.2 Prompt user for local destination path; reject empty/whitespace-only input with re-prompt
+  - [x] 3.3 Resolve destination to absolute path via `path.resolve()`
+  - [x] 3.4 If destination exists and is a file (not directory): warn with `chalk.red()` and re-prompt
+  - [x] 3.5 If destination exists and is a directory: display summary with `chalk.blue()` (file count, whether it's a git repo), ask user to confirm using existing directory
+  - [x] 3.6 If destination does not exist: run `execFileSync('git', ['clone', gitUrl, destPath], { timeout: 120000, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } })` — prevents injection, hangs, and SSH key prompts
+  - [x] 3.7 On clone failure: if `destPath` was created by the failed clone (didn't exist before), remove it (`fs.rmSync(destPath, { recursive: true, force: true })`). Then offer retry or skip
+  - [x] 3.8 If user skips after failure: fall back to `{ mode: 'same', path: '.' }`, log warning with `chalk.yellow('Falling back to current repository for {concern}')`
+  - [x] 3.9 Warn if destination resolves inside current repo
+
+- [x] Task 4: Integrate into wizard flow (AC: #1-#10)
+  - [x] 4.1 Call `collectRepoLayout(flags)` in `installWizard()` AFTER agent selection (after ~line 333) and BEFORE scope selection (~line 336)
+  - [x] 4.2 Pass the returned layout object forward to the installation pipeline context
+  - [x] 4.3 Store layout in the installation context so subsequent steps (config write, project-context) can access it
+  - [x] 4.4 Verify `--yes` mode without env vars bypasses all repo layout prompts (defaults to same)
+  - [x] 4.5 Verify `--yes` mode with env vars creates local-mode layout without prompts
+
+- [x] Task 5: Write unit tests (AC: #1-#10)
+  - [x] 5.1 Test `collectRepoLayout()` with `--yes` flag returns both as `same` mode
+  - [x] 5.2 Test `collectRepoLayout()` with `--yes` + env vars returns local mode with resolved paths
+  - [x] 5.3 Test local path validation: existing dir accepted, existing file rejected, non-existent warned
+  - [x] 5.4 Test remote flow: `execFileSync` called with correct args array (not string interpolation)
+  - [x] 5.5 Test clone failure: partial directory cleanup, skip fallback to same mode
+  - [x] 5.6 Test empty/whitespace input rejection for URL and path
+  - [x] 5.7 Test nested-repo warning when path is inside cwd
+
+## Dev Notes
+
+### Architecture Decision P2-10
+
+This story implements the installation wizard portion of architecture decision P2-10 (Multi-Repository Project Layout). The wizard goes in `bin/cli.js` as a new section AFTER the agent selection prompts.
+
+### CRITICAL: Correct Prompt Library
+
+The codebase uses the `prompts` npm package, NOT `inquirer`. See `bin/cli.js` line 3: `const prompts = require('prompts');`. Key syntax differences:
+- List/select prompts use `type: 'select'` (not `'list'`)
+- Choices use `{ title: 'Display text', value: 'value' }` (not `{ name, value }`)
+- Import: `const prompts = require('prompts');`
+
+### Code Pattern Reference (Corrected)
+
+```javascript
+// In bin/cli.js — new wizard section after agent selection
+async function collectRepoLayout(flags) {
+  // CI/CD mode: check env vars first, then default
+  if (flags.yes) {
+    const kbPath = process.env.MA_KNOWLEDGEBASE_PATH;
+    const sprintPath = process.env.MA_SPRINT_PATH;
+    return {
+      knowledgebase: kbPath
+        ? { mode: 'local', path: path.resolve(kbPath) }
+        : { mode: 'same', path: '.' },
+      sprintManagement: sprintPath
+        ? { mode: 'local', path: path.resolve(sprintPath) }
+        : { mode: 'same', path: '.' },
+    };
+  }
+
+  const layout = { knowledgebase: null, sprintManagement: null };
+  for (const concern of ['knowledgebase', 'sprintManagement']) {
+    const { mode } = await prompts({
+      type: 'select',
+      name: 'mode',
+      message: `Where is your ${concern} managed?`,
+      choices: [
+        { title: 'Current repository (default)', value: 'same' },
+        { title: 'Local path', value: 'local' },
+        { title: 'Remote git repository', value: 'remote' },
+      ]
+    });
+    // ... mode-specific handling
+  }
+  return layout;
+}
+```
+
+### SECURITY: Command Injection Prevention
+
+**NEVER** use `execSync()` with string interpolation for git clone. The git URL is user-provided and could contain shell metacharacters. Use `execFileSync` which passes arguments as an array, bypassing shell interpretation:
+
+```javascript
+// WRONG — command injection via URL
+execSync(`git clone "${gitUrl}" "${destPath}"`);
+
+// CORRECT — arguments passed as array, no shell
+const { execFileSync } = require('child_process');
+execFileSync('git', ['clone', gitUrl, destPath], {
+  timeout: 120000,
+  env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+  stdio: 'inherit'
+});
+```
+
+### Clone Failure Cleanup
+
+If a clone fails partway through, the destination directory may contain a partial/corrupt clone. Before offering retry, check if the directory was created by the clone attempt and remove it:
+
+```javascript
+const existedBefore = fs.existsSync(destPath);
+try {
+  execFileSync('git', ['clone', gitUrl, destPath], { ... });
+} catch (err) {
+  if (!existedBefore && fs.existsSync(destPath)) {
+    fs.rmSync(destPath, { recursive: true, force: true });
+  }
+  // offer retry or skip
+}
+```
+
+### Key Implementation Constraints
+
+1. **`prompts` library** (NOT `inquirer`): Use `type: 'select'` with `{ title, value }` choices — match existing `bin/cli.js` patterns
+2. **File location**: `bin/cli.js` (NOT `cli.js` at project root — there is no such file)
+3. **`execFileSync` for git clone**: Array args, no shell, prevents injection
+4. **Clone timeout**: 120 seconds, matching existing `GIT_TERMINAL_PROMPT: '0'` pattern in `lib/bmad.js`
+5. **Cross-platform paths**: `path.resolve()` for normalization — do NOT use hardcoded separators
+6. **No new dependencies**: Use `fs`, `path`, `child_process` (already available), `chalk` (already imported), `prompts` (already imported)
+7. **CI/CD env vars**: `MA_KNOWLEDGEBASE_PATH` and `MA_SPRINT_PATH` enable headless multi-repo setup
+
+### NFR Compliance
+
+| NFR | How This Story Addresses It |
+|-----|----------------------------|
+| NFR34 | Default "Current repository" preserves single-repo behavior — no change for existing users |
+| NFR35 | Git clone uses user-provided URL — works with internal GitLab, local network repos |
+| NFR9 | `path.resolve()` for cross-platform path handling |
+
+### Story Scope Boundary
+
+This story ONLY implements the wizard collection. It does NOT write to config.yaml or create `project-layout.yaml` — that is Story 16.2. This story returns the layout object to the caller.
+
+### Project Structure Notes
+
+- Primary file to modify: `bin/cli.js`
+- Wizard section placement: after agent selection (~line 333), before scope selection (~line 336)
+- The layout object is passed forward through the installation pipeline
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/architecture.md — Decision P2-10, lines 792-901]
+- [Source: _bmad-output/planning-artifacts/epics.md — Story 16.1, lines 1972-2008]
+- [Source: _bmad-output/planning-artifacts/prd.md — FR111-FR116, FR127, lines 574-598]
+- [Source: _bmad-output/planning-artifacts/prd.md — NFR34-NFR37, lines 655-660]
+- [Source: bin/cli.js — installWizard(), prompts library usage]
+
+## Dev Agent Record
+
+### Agent Model Used
+
+Claude Opus 4.6 (1M context)
+
+### Debug Log References
+
+None — implementation proceeded without errors.
+
+### Completion Notes List
+
+- Implemented `collectRepoLayout(flags)` function with full CI/CD (--yes) and interactive support
+- Implemented `collectLocalPath(concern)` helper for local path validation with re-prompt loops, directory/file checks, non-existent path warnings, and nested-repo detection
+- Implemented `collectRemotePath(concern)` helper for remote git clone flow with `execFileSync` (injection-safe), clone failure cleanup, retry/skip fallback, and nested-repo detection
+- Integrated `collectRepoLayout()` into `installWizard()` flow after agent selection, before scope selection
+- Created 13 unit tests in `test/repo-layout.test.js` covering: --yes defaults, env var resolution, structural code checks (execFileSync array args, clone cleanup, empty input rejection, nested-repo warning), and integration test
+- All 13 new tests pass, all existing tests pass (no regressions)
+- Added `repo-layout.test.js` to `package.json` test script
+- Exported `collectRepoLayout` from `bin/cli.js` for testability
+
+### Change Log
+
+- 2026-03-28: Implemented story 16.1 — repository layout wizard with all 5 tasks complete
+
+### File List
+
+- bin/cli.js (modified — added collectRepoLayout, collectLocalPath, collectRemotePath functions + integration)
+- test/repo-layout.test.js (new — 13 unit/integration tests)
+- package.json (modified — added repo-layout.test.js to test script)
+- _bmad-output/implementation-artifacts/sprint-status.yaml (modified — story status)
+- _bmad-output/implementation-artifacts/16-1-repository-layout-wizard.md (modified — task checkboxes, dev record)

package/_bmad-output/implementation-artifacts/done/16-2-config-storage-and-cross-reference.md

@@ -0,0 +1,180 @@
+# Story 16.2: Config Storage and Cross-Reference File
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **DevOps engineer**,
+I want the configured repo paths stored persistently and a cross-reference file created in the code repo,
+So that agents and BMAD workflows can discover the correct paths without re-running installation.
+
+## Acceptance Criteria
+
+1. When knowledgebase is configured at `d:/Code/kb-repo` and sprint management at `d:/Code/sprint-repo`, `_bmad/bmm/config.yaml` contains `knowledgebase_path` and `sprint_management_path` fields with those values (FR117)
+2. When multi-repo mode is configured, `_bmad-output/project-layout.yaml` is created in the CODE repository with `generated`, `knowledgebase` (mode, path, gitUrl), and `sprint_management` (mode, path) sections (FR122)
+3. When single-repo mode is configured (both set to "current repository"), config.yaml contains `knowledgebase_path: "."` and `sprint_management_path: "."` — and NO `project-layout.yaml` is created (NFR34)
+4. Running the installer multiple times with the same multi-repo configuration produces an identical `project-layout.yaml` except for the `generated` date field (NFR36 deterministic)
+5. `project-layout.yaml` is generated by ma-agents installer, not by bmad-method — it lives in `_bmad-output/` which is version-controlled (per F3)
+6. Path values in both YAML files are always double-quoted and use forward slashes (cross-platform safe)
+7. If config.yaml already contains `knowledgebase_path`/`sprint_management_path` from a previous run, the values are updated in place (not duplicated)
+8. When switching from multi-repo to single-repo, a stale `project-layout.yaml` is deleted (not left behind with outdated paths)
+
+## Tasks / Subtasks
+
+- [x] Task 1: Write repo layout to `_bmad/bmm/config.yaml` (AC: #1, #3, #6, #7)
+  - [x] 1.1 After `collectRepoLayout()` returns (Story 16.1), extract knowledgebase and sprint management paths
+  - [x] 1.2 Read existing `_bmad/bmm/config.yaml` content as string. If file does not exist, log error and skip (bmad-method should have created it)
+  - [x] 1.3 Normalize paths: `resolvedPath.replace(/\\/g, '/')` before writing
+  - [x] 1.4 For each field (`knowledgebase_path`, `sprint_management_path`): regex replace or append
+  - [x] 1.5 Always double-quote path values in YAML
+  - [x] 1.6 Wrap write in try/catch — non-fatal on permission errors
+  - [x] 1.7 For `same` mode, write `"."` as the path value
+
+- [x] Task 2: Generate `project-layout.yaml` for multi-repo mode (AC: #2, #4, #5, #6)
+  - [x] 2.1 Check if either concern is NOT `same` mode — if both are `same`, skip
+  - [x] 2.2 Ensure `_bmad-output/` directory exists
+  - [x] 2.3 Generate `_bmad-output/project-layout.yaml` using template string
+  - [x] 2.4 Only include `gitUrl` field when mode is `remote`
+  - [x] 2.5 Normalize all paths before writing
+  - [x] 2.6 Always double-quote path and gitUrl values
+
+- [x] Task 3: Handle single-repo mode and stale files (AC: #3, #8)
+  - [x] 3.1 When both concerns are `same` mode, do NOT create `project-layout.yaml`
+  - [x] 3.2 Delete stale `project-layout.yaml` when switching to single-repo
+  - [x] 3.3 Config.yaml still gets `"."` paths written
+
+- [x] Task 4: Handle mode changes on reinstall (AC: #7, #8)
+  - [x] 4.1 Update existing fields in-place via regex
+  - [x] 4.2 Mode changes regenerate project-layout.yaml
+  - [x] 4.3 Mode changes to both-same delete project-layout.yaml
+
+- [x] Task 5: Integrate into installation pipeline (AC: #1-#8)
+  - [x] 5.1 Place config write AFTER bmad-method installation completes
+  - [x] 5.2 Place project-layout.yaml generation after config write
+  - [x] 5.3 Log what was written
+  - [x] 5.4 Verify idempotency
+
+- [x] Task 6: Write unit tests (AC: #1-#8)
+  - [x] 6.1 Test config write: both-same writes `"."`, multi-repo writes absolute paths
+  - [x] 6.2 Test config idempotency
+  - [x] 6.3 Test config update: existing fields replaced in place, no duplicates
+  - [x] 6.4 Test project-layout.yaml: created for multi-repo, skipped for single-repo
+  - [x] 6.5 Test stale cleanup: switching to single-repo deletes existing project-layout.yaml
+  - [x] 6.6 Test path normalization: backslashes converted to forward slashes
+  - [x] 6.7 Test YAML quoting: double-quoted paths
+  - [x] 6.8 Test file permissions error: non-fatal, logged gracefully
+
+## Dev Notes
+
+### CRITICAL: Correct Config File Location
+
+**BMAD workflows read config from `_bmad/bmm/config.yaml`**, NOT `_bmad/core/config.yaml`. Every workflow.yaml in the codebase uses:
+```yaml
+config_source: "{project-root}/_bmad/bmm/config.yaml"
+```
+
+The architecture doc references `_bmad/core/config.yaml`, but the actual codebase uses `_bmad/bmm/config.yaml` for operational config that workflows consume. Write path fields to `_bmad/bmm/config.yaml` so workflows can resolve them at runtime.
+
+### Source of Truth Precedence
+
+Three files can contain repo layout information. Their roles and precedence:
+
+| File | Role | Authority |
+|------|------|-----------|
+| `_bmad/bmm/config.yaml` | **Runtime source of truth** — workflows read this at execution time | PRIMARY |
+| `_bmad-output/project-layout.yaml` | **Agent discovery file** — agents in code repo discover cross-repo paths without loading BMAD config | INFORMATIONAL |
+| `_bmad-output/project-context.md` | **Agent constitutional doc** — stamps paths into agent operating rules | INSTRUCTIONAL |
+
+If these ever disagree, `_bmad/bmm/config.yaml` wins.
+
+### Idempotent YAML Write Pattern
+
+The codebase avoids `js-yaml` as a dependency. Use regex-based find/replace for idempotent config writes:
+
+```javascript
+function writeConfigField(content, fieldName, value) {
+  const regex = new RegExp(`^${fieldName}:.*$`, 'm');
+  const newLine = `${fieldName}: "${value}"`;
+  if (regex.test(content)) {
+    return content.replace(regex, newLine); // update in place
+  }
+  // append (ensure trailing newline)
+  return content.trimEnd() + '\n' + newLine + '\n';
+}
+```
+
+### Stale File Cleanup
+
+When switching from multi-repo to single-repo, the `project-layout.yaml` must be deleted — not left behind. Agents reading a stale file would use outdated paths silently. This is a deliberate departure from the "leave it" approach in the original architecture, based on the adversarial review finding that stale files cause silent path misdirection.
+
+### Key Implementation Constraints
+
+1. **Write to `_bmad/bmm/config.yaml`**: This is where workflows actually read from — verified by checking `config_source` in all workflow.yaml files
+2. **No js-yaml dependency**: Use string templates and regex for YAML operations
+3. **Always double-quote path values**: Handles Windows drive letters (`C:`), spaces, and YAML-special chars (`#`, `%`, `{`, `}`)
+4. **Always normalize separators**: `.replace(/\\/g, '/')` on all paths before writing
+5. **Idempotent writes**: Regex replace existing fields, append only if missing — never duplicate
+6. **Delete stale files**: Remove `project-layout.yaml` when switching to single-repo
+7. **project-layout.yaml in `_bmad-output/`**: version-controlled per Epic 10 policy
+8. **Generated date**: `YYYY-MM-DD` format matching sprint-status.yaml convention
+
+### NFR Compliance
+
+| NFR | How This Story Addresses It |
+|-----|----------------------------|
+| NFR34 | Single-repo: write `"."` paths, delete any stale project-layout.yaml |
+| NFR36 | Deterministic: template string, only `generated` date varies |
+| NFR9 | Path normalization with forward slashes in YAML output |
+
+### Dependencies
+
+- **Story 16.1** must be complete — provides the `layout` object with mode/path/gitUrl for each concern
+- **bmad-method installation** must complete first — creates `_bmad/bmm/config.yaml`
+
+### Project Structure Notes
+
+- Config write target: `_bmad/bmm/config.yaml` (verified: all workflows use this as config_source)
+- Project-layout.yaml target: `_bmad-output/project-layout.yaml`
+- Integration point: after `bmad.installBmad()` completes in the installation pipeline
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/architecture.md — Decision P2-10, config storage section, lines 844-870]
+- [Source: _bmad-output/planning-artifacts/epics.md — Story 16.2, lines 2010-2052]
+- [Source: _bmad-output/planning-artifacts/prd.md — FR117, FR122, lines 582-587]
+- [Source: _bmad-output/planning-artifacts/prd.md — NFR34, NFR36, lines 657-659]
+- [Source: _bmad/bmm/workflows/4-implementation/create-story/workflow.yaml — config_source: _bmad/bmm/config.yaml]
+
+## Dev Agent Record
+
+### Agent Model Used
+
+Claude Opus 4.6 (1M context)
+
+### Debug Log References
+
+None — clean implementation.
+
+### Completion Notes List
+
+- Implemented `normalizePath()` utility for backslash-to-forward-slash conversion
+- Implemented `writeConfigField()` for idempotent regex-based YAML field writes (replace or append)
+- Implemented `writeRepoLayoutConfig()` to write `knowledgebase_path` and `sprint_management_path` to `_bmad/bmm/config.yaml`
+- Implemented `writeProjectLayoutYaml()` to generate `_bmad-output/project-layout.yaml` for multi-repo or delete stale file for single-repo
+- Integrated both into `installWizard()` as Step 3.6 after BMAD installation
+- 16 unit tests covering normalization, config writes, idempotency, stale cleanup, multi-repo/single-repo modes
+- All tests pass, no regressions
+
+### Change Log
+
+- 2026-03-28: Implemented story 16.2 — config storage and project-layout.yaml generation
+
+### File List
+
+- bin/cli.js (modified — added writeRepoLayoutConfig, writeProjectLayoutYaml, writeConfigField, normalizePath + integration)
+- test/config-storage.test.js (new — 16 tests)
+- package.json (modified — added test to script)
+- _bmad-output/implementation-artifacts/sprint-status.yaml (modified)
+- _bmad-output/implementation-artifacts/16-2-config-storage-and-cross-reference.md (modified)

package/_bmad-output/implementation-artifacts/done/16-3-project-context-multi-repo-section.md

@@ -0,0 +1,136 @@
+# Story 16.3: Project-Context Multi-Repo Section
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As an **AI agent**,
+I want project-context.md to include the configured repository paths,
+So that I know where to read and write planning and sprint artifacts.
+
+## Acceptance Criteria
+
+1. When multi-repo is configured with knowledgebase at `/path/to/kb` and sprint at `/path/to/sprint`, the generated project-context.md includes a "Repository Layout" section with both paths and usage instructions (FR118)
+2. When single-repo mode is configured, the "Repository Layout" section is omitted entirely from project-context.md — no empty headers, no leftover blank lines (NFR34 backward compatibility)
+3. When project-context.md already exists, the installer uses the **marker-based update pattern** (like the existing `ma-agents:manifest-paths` pattern) to insert or update the Repository Layout section between `<!-- ma-agents:repo-layout-start -->` and `<!-- ma-agents:repo-layout-end -->` markers. If markers don't exist yet, append the section with markers at the end of the "AI Agent Mandatory Rules" block. The file is NOT regenerated from scratch (preserves user customizations)
+4. The `project-context.template.md` template is updated with a `{{REPO_LAYOUT_SECTION}}` placeholder that resolves to the section content (with markers) or empty string
+5. When the layout config object is undefined or missing fields, the generator returns empty string (no crash)
+6. All paths in the generated section use forward slashes (backslashes normalized before markdown insertion)
+
+## Tasks / Subtasks
+
+- [x] Task 1: Update project-context template (AC: #1, #2, #4)
+  - [x] 1.1-1.5 Added `{{REPO_LAYOUT_SECTION}}` placeholder; clean removal for single-repo
+
+- [x] Task 2: Implement Repository Layout section generator (AC: #1, #2, #5, #6)
+  - [x] 2.1-2.7 `generateRepoLayoutSection(layout)` with guards, markers, mixed config, path normalization
+
+- [x] Task 3: Integrate with project-context generator (AC: #1, #2, #4, #5)
+  - [x] 3.1-3.5 Added `layout` parameter to `generateProjectContext()`, backward-compatible
+
+- [x] Task 4: Implement marker-based update for existing files (AC: #3)
+  - [x] 4.1-4.7 `updateProjectContextRepoLayout()` with marker update/insert, integrated into installWizard
+
+- [x] Task 5: Write/update unit tests (AC: #1-#6)
+  - [x] 5.1-5.7 12 new tests added to generate-project-context.test.js (27 total, all pass)
+
+## Dev Notes
+
+### CRITICAL: Marker-Based Update Pattern (Not "Never Modify")
+
+The adversarial review correctly identified that the original AC ("never modify existing project-context.md") contradicts the codebase's established pattern. The existing `updateProjectContextManifestPaths()` function in `lib/installer.js` already modifies existing files using HTML comment markers:
+
+```markdown
+<!-- ma-agents:manifest-paths-start -->
+  content here
+<!-- ma-agents:manifest-paths-end -->
+```
+
+This story uses the SAME pattern with `<!-- ma-agents:repo-layout-start -->` / `<!-- ma-agents:repo-layout-end -->` markers. This allows:
+- Fresh generation: placeholder replaced in template
+- Existing files: content between markers updated in place
+- User customizations outside markers: preserved
+
+### Generator Function Location (Confirmed)
+
+The generator function is `generateProjectContext()` in `lib/installer.js` (lines 143-200). It is an exported function with existing tests in `test/generate-project-context.test.js`. Adding the `layout` parameter changes the public API — tests MUST be updated.
+
+### Template Section Format
+
+```markdown
+<!-- ma-agents:repo-layout-start -->
+### Repository Layout
+- **Knowledgebase:** {{KNOWLEDGEBASE_PATH}}
+- **Sprint Management:** {{SPRINT_MANAGEMENT_PATH}}
+- When creating or reading planning artifacts, use the knowledgebase path
+- When creating or reading sprint/story artifacts, use the sprint management path
+<!-- ma-agents:repo-layout-end -->
+```
+
+### Key Implementation Constraints
+
+1. **Marker-based updates**: Use `<!-- ma-agents:repo-layout-start/end -->` markers — same pattern as manifest paths
+2. **Clean omission**: When single-repo, no markers, no section, no blank lines — truly omitted
+3. **Backward-compatible API**: `generateProjectContext(root, agents, layout)` — `layout` defaults to `null`, existing callers unaffected
+4. **Normalize backslashes**: All paths get `.replace(/\\/g, '/')` before markdown insertion — backslashes break markdown rendering
+5. **No new dependencies**: String template replacement, consistent with existing approach
+6. **Template file**: `lib/templates/project-context.template.md` (confirmed)
+7. **Existing test file**: `test/generate-project-context.test.js` — MUST be updated
+
+### NFR Compliance
+
+| NFR | How This Story Addresses It |
+|-----|----------------------------|
+| NFR34 | Single-repo: section omitted entirely — no visible change to existing project-context.md |
+| NFR37 | Agents get explicit path instructions — no hardcoded `_bmad-output/` assumptions |
+
+### Dependencies
+
+- **Story 16.2** provides the config values that determine whether multi-repo is active
+- **Epic 13** (project-context auto-generation) provides the template and generator function this story modifies
+
+### Project Structure Notes
+
+- Template file: `lib/templates/project-context.template.md`
+- Generator function: `generateProjectContext()` in `lib/installer.js` (lines 143-200)
+- Update function: `updateProjectContextManifestPaths()` in `lib/installer.js` — use as pattern reference
+- Existing tests: `test/generate-project-context.test.js`
+- Output: `_bmad-output/project-context.md`
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/architecture.md — Decision P2-10, project-context integration, lines 884-895]
+- [Source: _bmad-output/planning-artifacts/epics.md — Story 16.3, lines 2054-2085]
+- [Source: _bmad-output/planning-artifacts/prd.md — FR118, line 583]
+- [Source: _bmad-output/planning-artifacts/prd.md — NFR34, NFR37, lines 657-660]
+- [Source: lib/installer.js — generateProjectContext(), updateProjectContextManifestPaths()]
+- [Source: test/generate-project-context.test.js — existing tests to update]
+
+## Dev Agent Record
+
+### Agent Model Used
+Claude Opus 4.6 (1M context)
+
+### Debug Log References
+None.
+
+### Completion Notes List
+- Added `{{REPO_LAYOUT_SECTION}}` placeholder to `lib/templates/project-context.template.md`
+- Implemented `generateRepoLayoutSection(layout)` in `lib/installer.js` — generates markdown with markers for multi-repo, empty string for single-repo
+- Updated `generateProjectContext()` to accept optional `layout` parameter (backward-compatible)
+- Implemented `updateProjectContextRepoLayout()` for marker-based updates to existing project-context.md
+- Integrated into `installWizard()` — calls `updateProjectContextRepoLayout()` after skill installation
+- 12 new tests added to `test/generate-project-context.test.js`, all 27 pass
+
+### Change Log
+- 2026-03-28: Implemented story 16.3 — project-context multi-repo section
+
+### File List
+- lib/installer.js (modified — generateRepoLayoutSection, updateProjectContextRepoLayout, generateProjectContext layout param)
+- lib/templates/project-context.template.md (modified — added REPO_LAYOUT_SECTION placeholder)
+- bin/cli.js (modified — import updateProjectContextRepoLayout, call after skill install)
+- test/generate-project-context.test.js (modified — 12 new tests)
+- _bmad-output/implementation-artifacts/sprint-status.yaml (modified)
+- _bmad-output/implementation-artifacts/16-3-project-context-multi-repo-section.md (modified)