phasegate 0.152.8 → 0.152.9

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.152.9] - 2026-05-13
+
+### Added
+
+- **WI-171 / WI-172 / WI-173 / WI-174 — user onboarding and agent-driven setup** — adds first-run recipes and troubleshooting guides, managed `AGENTS.md` / `CLAUDE.md` setup sections, dedicated AGENTS lesson pointer refresh, `setup:agent` setup planning/apply flow, and `config:plan` configuration-change intent planning.
+
 ## [0.152.8] - 2026-05-13
 
 ### Changed

package/README.md

@@ -60,6 +60,8 @@ The point is not just to fail the edit. The error gives the AI agent enough stru
 
 ## Quick Start
 
+For a guided first run, start with [Getting Started](docs/guide/getting-started.md). It maps new repo, existing repo, CI-only, agent-hook, and strict rollout paths to the next command and success state. <!-- @work-item-id WI-171 -->
+
 ### Requirements
 
 Node.js >= 18, npm >= 9, TypeScript 5.x
@@ -98,7 +100,16 @@ npx phasegate install --apply
 npx phasegate doctor
 ```
 
-`install` merges PhaseGate into the current project without discarding existing Claude/Codex hooks or Husky scripts. It reports planned changes before writing, adds package scripts and the `phasegate` devDependency, creates agent skill links, writes the CI workflow when missing, and records managed files in `.phasegate/manifest.json`. If an existing file needs a forced managed update, run `npx phasegate install --apply --force`; PhaseGate backs up replaced files under `.phasegate/backups/`.
+`install` merges PhaseGate into the current project without discarding existing Claude/Codex hooks or Husky scripts. It reports planned changes before writing, adds package scripts and the `phasegate` devDependency, creates agent skill links, writes `AGENTS.md` / `CLAUDE.md` PhaseGate managed sections for the selected agent targets, writes the CI workflow when missing, and records managed files in `.phasegate/manifest.json`. If an existing file needs a forced managed update, run `npx phasegate install --apply --force`; PhaseGate backs up replaced files under `.phasegate/backups/`. <!-- @work-item-id WI-174 -->
+
+For agent-driven setup planning, use:
+
+```bash
+npx phasegate setup:agent --intent recommended --dry-run --json
+npx phasegate config:plan --intent codex-hooks --dry-run --json
+```
+
+The first command reports detected setup state, missing questions, planned managed targets, rollback, and validation. The second maps a configuration change intent to files, commands, risks, and checks. <!-- @work-item-id WI-172, WI-173 -->
 
 To remove PhaseGate from that project later, run:
 
@@ -507,6 +518,8 @@ README keeps only the entry points most users need. The full public/compatibilit
 | `doctor` | Diagnose silent or partial installations (`--json`, `--strict`, `--report-out <path>`). `--report-out` is an explicit file path, not `reporting.outputDir`. |
 | `uninstall --dry-run` / `--apply` | Remove PhaseGate-managed files and managed blocks using `.phasegate/manifest.json`, preserving user content. |
 | `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to the current package templates and refresh manifest hashes. |
+| `setup:agent --dry-run` / `--apply` | Diagnose repository setup and produce or apply an agent-readable setup plan with questions, risks, rollback, and validation. |
+| `config:plan --intent <intent>` | Map a safe configuration-change intent to target files, commands, risks, rollback, and validation. |
 | `lint` / `phasegate:lint` | Run L1 Biome AST checks. The `phasegate:*` form is a binary subcommand, not an npm script unless `package.json` defines it locally. |
 | `validate --layer <L1-L4\|all>` | Run validators for the specified layer (`--layer L0` prints runtime hook guidance). `--fail-on-warning` / `--no-fail-on-warning` override config. |
 | `ci-check` | Full CI check (L2-L4; disabled L4 is reported as skipped). Supports `--quick`, `--fail-on-reject`, `--dry-run`, and `--files`. |
@@ -547,6 +560,9 @@ See the [CLI Reference](docs/guide/cli-reference.md) for the complete catalog an
 Detailed guides are available under `docs/guide/`:
 
 - [Installation](docs/guide/installation.md) -- Detailed install and setup instructions
+- [Getting Started](docs/guide/getting-started.md) -- First-run, daily-use, CI-use, and agent-use paths
+- [Recipes](docs/guide/recipes.md) -- Focused onboarding and configuration recipes
+- [Troubleshooting](docs/guide/troubleshooting.md) -- Doctor finding, repairHint, suggestedSkill, and setup recovery guide
 - [Configuration](docs/guide/configuration.md) -- `phasegate.config.json` full reference
 - [CLI Reference](docs/guide/cli-reference.md) -- All CLI commands and options
 - [Skills Overview](docs/guide/skills-overview.md) -- 30 skills with AIDLC execution order

package/docs/guide/cli-reference.md

@@ -23,10 +23,12 @@ Command names in this document are split into three surfaces:
 | Command | Description |
 |---|---|
 | `init --name <name>` | Legacy-compatible bootstrap for new projects: deploy skills, generate config, and optionally add hooks/CI. Options: `--preset <full\|standard\|minimal\|custom>`, `--skills <core\|all>`, `--agent <claude\|codex\|both>`, `--workflow <standard\|strict>`, `--with-husky`, `--with-ci`, `--yes`. |
-| `install --dry-run` / `--apply` | Idempotently merge PhaseGate into an existing project, preserve user content, add package scripts/devDependency, and write `.phasegate/manifest.json`. `--force` replaces managed targets after backup. |
+| `install --dry-run` / `--apply` | Idempotently merge PhaseGate into an existing project, preserve user content, add package scripts/devDependency, create selected `AGENTS.md` / `CLAUDE.md` managed sections, and write `.phasegate/manifest.json`. `--agent <claude\|codex\|both>`, `--skills <core\|all>`, and `--workflow <standard\|strict>` affect rendered agent context; `--force` replaces managed targets after backup. |
 | `doctor` | Diagnose silent or partial installations and report repair hints (`--json`, `--strict`, `--report-out <path>`). `--report-out` writes exactly to the supplied path, not to `reporting.outputDir`. |
 | `uninstall --dry-run` / `--apply` | Remove PhaseGate-managed files and managed blocks using `.phasegate/manifest.json`; `--force` handles managed conflict cases. |
 | `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to current package templates and refresh manifest hashes; `--force` allows managed-file replacement with backup. |
+| `setup:agent` | Agent-readable setup planner and optional apply path. Options: `--intent <minimal\|recommended\|strict\|ci-only\|agent-hooks\|retrofit>`, `--agent <claude\|codex\|both>`, `--workflow <standard\|strict>`, `--with-husky`, `--with-ci`, `--dry-run`, `--apply`, `--json`. <!-- @work-item-id WI-172 --> |
+| `config:plan` | Agent-readable configuration change planner. Options: `--intent <l4-strict\|codex-hooks\|ci-fail-on-warning\|baseline-reset\|quick-mode-strict>`, `--dry-run`, `--json`. <!-- @work-item-id WI-173 --> |
 | `update-skills` | Compatibility alias for `reconcile`; use `reconcile` for new automation. |
 | `scaffold-wi <unit> <type>` | Create `docs/inception/{unit}/WI-XXX/description.md` using the next free WI number. |
 | `emit-agent-rules` | Print the AGENTS.md / CLAUDE.md WI workflow rules block. |
@@ -374,7 +376,7 @@ ISSUE-005 P3-10 で明確化された境界:
 |---|---|---|
 | `ci:generate-template` | `--preset <id>`（省略時 `standard`） `--type <type>` `--render` `--json` | Generate CI/CD template |
 | `ci:migrate-agents-md` | `--dry-run` `--validate-only` `--json` | Migrate AGENTS.md to pointer format |
-| `ci:auto-refresh-agent-context` | `--dry-run` `--apply` `--json` | Refresh AGENTS.md pointers and CLAUDE.md standard sections |
+| `ci:auto-refresh-agent-context` | `--dry-run` `--apply` `--json` | Refresh AGENTS.md lesson pointers in a dedicated section and CLAUDE.md standard sections without replacing user-owned agent instructions |
 | `refresh-claude-md` | `--dry-run` `--apply` `--json` | Refresh CLAUDE.md while preserving the user-owned section |
 | `p2:check-agent-context` | `--threshold-days <n>` `--json` | Check AGENTS.md / CLAUDE.md freshness |
 | `ci:check-repetition` | `--code <errorCode>` `--reset` `--json` | Detect repetitive errors |

package/docs/guide/configuration.md

@@ -8,6 +8,15 @@ This file is the **Single Source of Truth** for all quality configuration in a P
 
 It is not the whole setup state. Hook JSON, Husky scripts, CI workflow files, skill links, `.phasegate/manifest.json`, runtime reports, and Codex user-level feature flags are tracked separately. Use [Setup Artifacts](setup-artifacts.md) when auditing whether a project is fully installed. <!-- @work-item-id WI-152 -->
 
+For agent-assisted changes, preview the intent before editing the config:
+
+```bash
+npx phasegate config:plan --intent l4-strict --dry-run --json
+npx phasegate config:plan --intent quick-mode-strict --dry-run --json
+```
+
+The plan identifies target fields, managed artifacts, commands, validation, risks, and rollback so an agent can explain the change before applying it. <!-- @work-item-id WI-173 -->
+
 ### Full Reference
 
 ```jsonc

package/docs/guide/getting-started.md

@@ -0,0 +1,64 @@
+# Getting Started
+
+<!-- @work-item-id WI-171 -->
+
+Use this page when you want the shortest path from "PhaseGate is installed" to "the next command is obvious".
+
+## First Run
+
+Start with one question: what kind of repository are you setting up?
+
+| Answer | Command | Success state |
+|---|---|---|
+| New project with agent hooks | `npx phasegate init --name <project> --agent both --with-husky --with-ci` | `phasegate.config.json`, skills, hooks, agent context files, Husky, and CI targets exist |
+| Existing repository | `npx phasegate install --dry-run` then `npx phasegate install --apply` | Existing hooks/scripts are preserved and `.phasegate/manifest.json` records managed targets |
+| CI-only rollout | `npx phasegate setup:agent --intent ci-only --with-ci --dry-run --json` | The plan explains CI changes without requiring local hooks |
+| Codex-only project | `npx phasegate init --agent codex --with-husky` | `.codex/hooks.json`, `AGENTS.md`, `.codex/skills`, and pre-commit backstop are present |
+| Strict validation rollout | `npx phasegate setup:agent --intent strict --dry-run --json` | The plan lists strict checks, L4 risk, rollback, and validation commands |
+
+After any setup path:
+
+```bash
+npx phasegate doctor
+npx phasegate phasegate:check-ready
+npx phasegate validate --layer L2 --format human
+```
+
+The first successful run is:
+
+- `doctor` has no unexpected red finding for the targets you chose.
+- `phasegate:check-ready` exits successfully.
+- L2 validators pass or report only issues you intentionally left for a later rollout.
+- The active agent can read `AGENTS.md` or `CLAUDE.md` and see the PhaseGate managed instructions.
+
+## Daily Use
+
+```bash
+npx phasegate work-items:status --dry-run
+npx phasegate validate --layer L2 --format human
+npx phasegate phasegate:status --json
+```
+
+Use `work-items:status` before commit when a WI is close to completion. Use `phasegate:status --json` when an agent needs machine-readable hook, baseline, and validator health.
+
+## Agent Use
+
+```bash
+npx phasegate setup:agent --dry-run --json
+npx phasegate config:plan --intent codex-hooks --dry-run --json
+```
+
+`setup:agent` reads repository setup state and returns missing targets, questions, risk, rollback, and validation steps. `config:plan` maps natural-language change intents such as "enable Codex hooks" or "make L4 stricter" to concrete files, commands, and checks.
+
+## CI Use
+
+```bash
+npx phasegate ci:generate-template --type aidlc-gate --render
+npx phasegate validate --layer all --format ci
+```
+
+For warning-as-failure rollout, preview the change first:
+
+```bash
+npx phasegate config:plan --intent ci-fail-on-warning --dry-run --json
+```

package/docs/guide/installation.md

@@ -17,7 +17,7 @@ Or add it directly to your `package.json`:
 ```json
 {
   "devDependencies": {
-    "phasegate": "^0.152.8"
+    "phasegate": "^0.152.9"
   }
 }
 ```
@@ -38,7 +38,7 @@ npx phasegate init --name <project-name>
 
 This deploys 30 skills to `skills/`, creates the agent-facing skill links (for example `.claude/skills/` or `.codex/skills/`), and generates `phasegate.config.json`.
 
-`init` is the legacy-compatible bootstrap path for new projects. Use `install` when the project may already have hooks, package scripts, or CI files that should be preserved.
+`init` is the legacy-compatible bootstrap path for new projects. It also runs the structured install path for the selected agent target so `CLAUDE.md` and/or `AGENTS.md` receive a PhaseGate managed section. Use `install` when the project may already have hooks, package scripts, or CI files that should be preserved. <!-- @work-item-id WI-174 -->
 
 For Codex, project initialization stops at the project boundary. After `npx phasegate init --agent codex`, enable the Codex CLI feature flag manually:
 
@@ -56,7 +56,16 @@ npx phasegate install --apply
 npx phasegate doctor
 ```
 
-`install --dry-run` reports whether each target will be created, merged, skipped, or refused. `install --apply` performs the merge, adds package scripts and the `phasegate` devDependency, creates `.claude/skills` and `.codex/skills` links, writes `.github/workflows/phasegate-aidlc-gate.yml` when CI is enabled, and records managed entries in `.phasegate/manifest.json`. See [Setup Artifacts](setup-artifacts.md) for the full managed target, generated artifact, runtime state, legacy artifact, and user-level setting inventory. <!-- @work-item-id WI-152 --> <!-- @work-item-id WI-169 -->
+`install --dry-run` reports whether each target will be created, merged, skipped, or refused. `install --apply` performs the merge, adds package scripts and the `phasegate` devDependency, creates `.claude/skills` and `.codex/skills` links, writes `CLAUDE.md` / `AGENTS.md` managed sections for selected agent targets, writes `.github/workflows/phasegate-aidlc-gate.yml` when CI is enabled, and records managed entries in `.phasegate/manifest.json`. See [Setup Artifacts](setup-artifacts.md) for the full managed target, generated artifact, runtime state, legacy artifact, and user-level setting inventory. <!-- @work-item-id WI-152 --> <!-- @work-item-id WI-169 --> <!-- @work-item-id WI-174 -->
+
+For agent-readable planning before writing files:
+
+```bash
+npx phasegate setup:agent --intent recommended --dry-run --json
+npx phasegate setup:agent --intent strict --with-ci --with-husky --dry-run --json
+```
+
+The setup plan includes detected state, questions, planned changes, risks, rollback, and validation commands. <!-- @work-item-id WI-172 -->
 
 If a managed update must replace existing custom content, use:
 
@@ -73,7 +82,7 @@ npx phasegate uninstall --dry-run
 npx phasegate uninstall --apply
 ```
 
-`uninstall` reads `.phasegate/manifest.json`, deletes files that PhaseGate created, removes only PhaseGate-managed portions from merged JSON, Husky, and `package.json` files, and archives the manifest as `.phasegate/uninstalled-<timestamp>.json`. If a managed file was modified after install, `uninstall --apply` refuses that entry until you rerun with `--force`, which creates a backup under `.phasegate/backups/uninstall-<timestamp>/`.
+`uninstall` reads `.phasegate/manifest.json`, deletes files that PhaseGate created, removes only PhaseGate-managed portions from merged JSON, markdown agent context files, Husky, and `package.json` files, and archives the manifest as `.phasegate/uninstalled-<timestamp>.json`. If a managed file was modified after install, `uninstall --apply` refuses that entry until you rerun with `--force`, which creates a backup under `.phasegate/backups/uninstall-<timestamp>/`. <!-- @work-item-id WI-174 -->
 
 After upgrading PhaseGate, reconcile existing managed files with the bundled templates from the new version:
 

package/docs/guide/recipes.md

@@ -0,0 +1,65 @@
+# Recipes
+
+<!-- @work-item-id WI-171, WI-172, WI-173 -->
+
+## First-Run Recipe
+
+```bash
+npm install --save-dev phasegate
+npx phasegate setup:agent --intent recommended --dry-run --json
+npx phasegate install --apply
+npx phasegate doctor
+```
+
+Use this when you want an existing repository to keep user-owned hooks, scripts, and CI files. The dry-run explains the managed targets before any file is written.
+
+## Retrofit Recipe
+
+```bash
+npx phasegate setup:agent --intent retrofit --dry-run --json
+npx phasegate install --dry-run
+npx phasegate install --apply
+npx phasegate baseline --dry-run
+```
+
+Use this when a repository already has meaningful history or custom automation. Treat any refused target as an agent-assisted review task instead of forcing it blindly.
+
+## Agent Hooks Recipe
+
+```bash
+npx phasegate setup:agent --intent agent-hooks --agent both --with-husky --dry-run --json
+npx phasegate install --agent both --apply
+codex features enable codex_hooks
+npx phasegate doctor --json
+```
+
+The repository-managed portion covers `.claude/settings.json`, `.codex/hooks.json`, `CLAUDE.md`, `AGENTS.md`, skills links, and the Husky backstop. The Codex user-level feature flag remains a local manual setting.
+
+## CI Recipe
+
+```bash
+npx phasegate setup:agent --intent ci-only --with-ci --dry-run --json
+npx phasegate install --apply
+npx phasegate ci:generate-template --type aidlc-gate --render
+```
+
+Use this when local hooks are not part of the rollout. The plan still includes validation and rollback steps so the agent can explain what changed.
+
+## Strict L4 Recipe
+
+```bash
+npx phasegate config:plan --intent l4-strict --dry-run --json
+npx phasegate validate --layer L4 --fail-on-warning --format human
+```
+
+Only enable fail-on-warning after reviewing the drift, consistency, dead-code, pointer, and freshness findings. The plan output identifies the config fields and validations the agent should cite in its change summary.
+
+## Configuration Change Recipe
+
+```bash
+npx phasegate config:plan --intent quick-mode-strict --dry-run --json
+npx phasegate check-change-category --paths <changed-files> --format json
+npx phasegate ci-check --quick --dry-run
+```
+
+Use `config:plan` before changing `phasegate.config.json`. It separates repo-managed artifacts from user-level settings and lists the checks needed after the change.

package/docs/guide/setup-artifacts.md

@@ -10,7 +10,7 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 
 | Class | Examples | Owner | Lifecycle |
 |---|---|---|---|
-| Managed target | `.claude/settings.json`, `.codex/hooks.json`, `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`, `.github/workflows/phasegate-aidlc-gate.yml`, `.claude/skills`, `.codex/skills`, `package.json` PhaseGate scripts/devDependency | PhaseGate managed block or symlink plus user content | Created or merged by `install`, refreshed by `reconcile`, removed or reversed by `uninstall` |
+| Managed target | `.claude/settings.json`, `.codex/hooks.json`, `CLAUDE.md`, `AGENTS.md`, `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`, `.github/workflows/phasegate-aidlc-gate.yml`, `.claude/skills`, `.codex/skills`, `package.json` PhaseGate scripts/devDependency | PhaseGate managed block or symlink plus user content | Created or merged by `install`, refreshed by `reconcile`, removed or reversed by `uninstall` |
 | Configuration | `phasegate.config.json`, `package.json` | User owned, PhaseGate assisted | Created by `init`; `install` may merge scripts/devDependency into `package.json` |
 | Generated artifact | `.phasegate/manifest.json`, `.phasegate/backups/*`, `.phasegate/uninstalled-*.json`, `.phasegate/baseline.json` | PhaseGate | Written by lifecycle commands and validators; safe to regenerate only through the owning command |
 | Runtime state/report | `.phasegate/hook-skip-events.jsonl`, explicit `doctor --report-out <path>` output, `reports/regression/*`, resolved `reporting.outputDir` reports | PhaseGate command output | Produced while hooks, doctor, and validation commands run |
@@ -22,12 +22,15 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 `install --apply` and `reconcile --apply` manage only explicit targets. The current structured lifecycle covers:
 
 - Agent hook JSON: `.claude/settings.json`, `.codex/hooks.json`
+- Agent context files: `CLAUDE.md` and `AGENTS.md` managed sections. `AGENT.md` singular is not a PhaseGate managed target; treat it as user-owned content or migrate it manually. <!-- @work-item-id WI-174 -->
 - Husky scripts when requested: `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`
 - CI workflow when requested: `.github/workflows/phasegate-aidlc-gate.yml`
 - Agent skill links: `.claude/skills`, `.codex/skills`
 - Package metadata: PhaseGate scripts and `devDependencies.phasegate` in `package.json`
 - Manifest: `.phasegate/manifest.json`
 
+`AGENTS.md` has two PhaseGate sections with separate ownership. `<!-- phasegate:managed-section:start -->` contains standard setup/WI workflow instructions. `<!-- phasegate:lesson-pointers:start -->` is reserved for `ci:auto-refresh-agent-context` lesson pointers. Refreshing lesson pointers must not replace the standard managed section or user-owned content. <!-- @work-item-id WI-174 -->
+
 `init --with-ci` still deploys the legacy-compatible template set, including `.github/workflows/aidlc-gate.yml`, `.github/workflows/consistency-check.yml`, and `.github/workflows/agent-context-refresh.yml`. Structured `install` uses `.github/workflows/phasegate-aidlc-gate.yml` so it can coexist with existing project CI without taking over a generic workflow filename.
 
 ## Doctor Findings

package/docs/guide/troubleshooting.md

@@ -0,0 +1,60 @@
+# Troubleshooting
+
+<!-- @work-item-id WI-171, WI-172, WI-173 -->
+
+Start with:
+
+```bash
+npx phasegate doctor --json
+```
+
+Each finding has a severity, a repair mode, and optional next-step fields.
+
+| Field | Meaning |
+|---|---|
+| `severity` | `red` blocks the expected setup state; `warn` needs review but may be acceptable for partial rollout |
+| `repairMode` | `mechanical` can be handled by PhaseGate commands; `ai-assisted` needs an agent to preserve user intent; `manual` needs human review |
+| `repairHint` | Copyable command for mechanical repair |
+| `suggestedSkill` | Agent skill to invoke when a merge or setup choice needs reasoning |
+
+## Common Findings
+
+| Finding | First action |
+|---|---|
+| `claude-hook-missing` | `npx phasegate install --agent claude --dry-run` |
+| `codex-hook-missing` | `npx phasegate install --agent codex --dry-run` |
+| `husky-pre-commit-missing` | `npx phasegate setup:agent --intent agent-hooks --with-husky --dry-run --json` |
+| `ci-workflow-missing` | `npx phasegate setup:agent --intent ci-only --with-ci --dry-run --json` |
+| agent context drift | `npx phasegate reconcile --dry-run` |
+
+## Refused Managed Target
+
+If `install`, `reconcile`, or `uninstall` refuses a target, do not immediately force it. Inspect the diff and ask the agent to explain:
+
+- which file is repo-managed and which part is user-owned;
+- why the target cannot be merged mechanically;
+- what backup and rollback path will exist if `--force` is used;
+- which validation commands will be run afterward.
+
+## Codex Hooks Do Not Fire
+
+Check both project and user-level state:
+
+```bash
+npx phasegate doctor --json
+codex features enable codex_hooks
+npx phasegate phasegate:status --json
+```
+
+Native Codex `apply_patch` writes are validated by the pre-commit backstop. Bash-based writes can be blocked before execution when hooks are enabled.
+
+## Agent Setup Is Ambiguous
+
+Use the planner instead of guessing:
+
+```bash
+npx phasegate setup:agent --intent retrofit --dry-run --json
+npx phasegate config:plan --intent codex-hooks --dry-run --json
+```
+
+The planner output is intentionally agent-readable: detected state, questions, planned targets, risks, rollback, and validation commands are all explicit.

package/docs/templates/agent-context/AGENTS.md.template.md

@@ -0,0 +1,45 @@
+# AGENTS.md
+
+<!-- @work-item-id WI-174 -->
+
+<!-- phasegate:managed-section:start -->
+## PhaseGate Managed Instructions
+
+### Required Documents
+
+- `docs/folder_management_rules.md`
+- `docs/principles/architecture-philosophy.md`
+- `docs/principles/testing-rules.md`
+
+### Workflow
+
+- Create or update the relevant `docs/inception/**/WI-XXX/` work item before planning, design, implementation, or tests.
+- Reflect accepted design into `docs/product/...` with `@work-item-id WI-XXX` before changing source files.
+- Run the relevant PhaseGate checks after changing docs, source, hooks, skills, or setup artifacts.
+- Do not bypass git hooks unless the user explicitly approves the reason, residual risk, and replacement validation.
+
+### Setup State
+
+- Agent target: `{{PHASEGATE_AGENT}}`
+- Skill set: `{{PHASEGATE_SKILLS_MODE}}`
+- Workflow mode: `{{PHASEGATE_WORKFLOW}}`
+- Husky hooks: `{{PHASEGATE_HUSKY_STATE}}`
+- CI workflow: `{{PHASEGATE_CI_STATE}}`
+
+### Common Commands
+
+{{PHASEGATE_COMMANDS}}
+
+### Codex Notes
+
+- Enable native hook execution with `codex features enable codex_hooks` when Codex hooks are installed.
+- Keep local-only Codex settings outside repository-managed targets unless PhaseGate explicitly reports them as managed.
+<!-- phasegate:managed-section:end -->
+
+<!-- phasegate:lesson-pointers:start -->
+<!-- lesson pointers are managed by phasegate ci:auto-refresh-agent-context -->
+<!-- phasegate:lesson-pointers:end -->
+
+<!-- phasegate:user-section:start -->
+Project-specific agent instructions go here.
+<!-- phasegate:user-section:end -->

package/docs/templates/agent-context/CLAUDE.md.template.md

@@ -1,5 +1,8 @@
 # CLAUDE.md
 
+<!-- @work-item-id WI-174 -->
+
+<!-- phasegate:managed-section:start -->
 ## 必読ドキュメント
 
 - `docs/folder_management_rules.md`
@@ -27,3 +30,4 @@
 ## Agent Context Refresh
 
 Run `phasegate ci:auto-refresh-agent-context --dry-run` to preview updates and `phasegate ci:auto-refresh-agent-context --apply` to write AGENTS.md / CLAUDE.md.
+<!-- phasegate:managed-section:end -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.152.8",
+  "version": "0.152.9",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/ci-governance/infrastructure/adapters/agents-md-file-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit ci-governance
+ * @work-item-id WI-174
  *
  * AgentsMdPort実装（AGENTS.mdファイルI/O）
  */
@@ -13,6 +14,7 @@ import { PointerEntry } from '../../domain/value-objects/pointer-entry.js';
 
 export class AgentsMdFileAdapter implements AgentsMdPort {
   private readonly filePath: string;
+  private lastReadContent: string | null = null;
 
   constructor(baseDir: string) {
     this.filePath = path.join(baseDir, 'AGENTS.md');
@@ -21,8 +23,10 @@ export class AgentsMdFileAdapter implements AgentsMdPort {
   async read(): Promise<AgentsMdPointer> {
     try {
       const content = await fs.readFile(this.filePath, 'utf-8');
+      this.lastReadContent = content;
       return this.parseAgentsMd(content);
     } catch {
+      this.lastReadContent = null;
       return AgentsMdPointer.create();
     }
   }
@@ -36,7 +40,7 @@ export class AgentsMdFileAdapter implements AgentsMdPort {
       before = 0;
     }
 
-    const content = this.serializeAgentsMd(pointer);
+    const content = this.serializeAgentsMd(pointer, this.lastReadContent ?? null);
     await fs.writeFile(this.filePath, content, 'utf-8');
     const after = content.split('\n').length;
 
@@ -81,11 +85,28 @@ export class AgentsMdFileAdapter implements AgentsMdPort {
     return AgentsMdPointer.create(pointers, adrLinks);
   }
 
-  private serializeAgentsMd(pointer: AgentsMdPointer): string {
-    const lines: string[] = ['# AGENTS.md', ''];
+  private serializeAgentsMd(pointer: AgentsMdPointer, existing: string | null): string {
+    const section = this.serializeLessonPointerSection(pointer);
+    if (existing !== null && existing.trim().length > 0) {
+      const start = '<!-- phasegate:lesson-pointers:start -->';
+      const end = '<!-- phasegate:lesson-pointers:end -->';
+      const pattern = new RegExp(`${this.escapeRegExp(start)}[\\s\\S]*?${this.escapeRegExp(end)}`);
+      if (pattern.test(existing)) {
+        return existing.replace(pattern, section.trim()).replace(/\s*$/, '\n');
+      }
+      return `${existing.replace(/\s*$/, '\n\n')}${section}`;
+    }
+    return ['# AGENTS.md', '', section].join('\n');
+  }
+
+  private serializeLessonPointerSection(pointer: AgentsMdPointer): string {
+    const lines: string[] = [
+      '<!-- phasegate:lesson-pointers:start -->',
+      '## PhaseGate Lesson Pointers',
+      '',
+    ];
 
     if (pointer.pointers.length > 0) {
-      lines.push('## Pointers', '');
       for (const entry of pointer.pointers) {
         if (entry.isCommand()) {
           lines.push(`- [cmd:${entry.key}](${entry.command ?? ''}) ${entry.description}`);
@@ -97,13 +118,18 @@ export class AgentsMdFileAdapter implements AgentsMdPort {
     }
 
     if (pointer.adrLinks.length > 0) {
-      lines.push('## ADR Links', '');
+      lines.push('### ADR Links', '');
       for (const adr of pointer.adrLinks) {
         lines.push(`- ADR: ${adr}`);
       }
       lines.push('');
     }
 
+    lines.push('<!-- phasegate:lesson-pointers:end -->', '');
     return lines.join('\n');
   }
+
+  private escapeRegExp(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
 }

package/scripts/harness/installation/application/usecases/run-install.ts

@@ -1,6 +1,7 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-146
+// @work-item-id WI-174
 
 import { mkdir, readFile, writeFile, copyFile, chmod, access, lstat, readlink, symlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -12,7 +13,7 @@ import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.j
 import type { HashCalculatorPort } from "../ports/hash-calculator-port.js";
 
 type InstallAction = "missing" | "will-merge" | "will-skip" | "will-overwrite";
-type StrategyType = "json" | "shell" | "yaml-add" | "package-json";
+type StrategyType = "json" | "shell" | "yaml-add" | "package-json" | "markdown-managed";
 
 export interface InstallPlanItem {
   readonly path: string;
@@ -36,6 +37,9 @@ export interface RunInstallInput {
   readonly includeCodex?: boolean;
   readonly includeHusky?: boolean;
   readonly includeCi?: boolean;
+  readonly skillSet?: "core" | "all";
+  readonly workflow?: "standard" | "strict";
+  readonly agent?: "claude" | "codex" | "both";
 }
 
 export interface RunInstallResult {
@@ -58,6 +62,8 @@ const PHASEGATE_SCRIPT_VERSION = "^0.0.0";
 
 const SHELL_BEGIN = "# === phasegate managed (BEGIN) ===";
 const SHELL_END = "# === phasegate managed (END) ===";
+const MARKDOWN_BEGIN = "<!-- phasegate:managed-section:start -->";
+const MARKDOWN_END = "<!-- phasegate:managed-section:end -->";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -131,6 +137,50 @@ function mergeShell(existing: string | null, incoming: string): string {
   return `${existing.replace(/\s*$/, "\n\n")}${block}\n`;
 }
 
+function managedMarkdownBlock(content: string): string {
+  const start = content.indexOf(MARKDOWN_BEGIN);
+  const end = content.indexOf(MARKDOWN_END);
+  if (start === -1 || end === -1 || end < start) return content.trim();
+  return content.slice(start, end + MARKDOWN_END.length).trim();
+}
+
+function mergeManagedMarkdown(existing: string | null, incoming: string): string {
+  const block = managedMarkdownBlock(incoming);
+  if (existing === null || existing.trim().length === 0) return `${incoming.trim()}\n`;
+  const pattern = new RegExp(`${escapeRegExp(MARKDOWN_BEGIN)}[\\s\\S]*?${escapeRegExp(MARKDOWN_END)}`);
+  if (pattern.test(existing)) return existing.replace(pattern, block).replace(/\s*$/, "\n");
+  return `${block}\n\n${existing.replace(/\s*$/, "\n")}`;
+}
+
+function renderAgentContextTemplate(
+  template: string,
+  options: {
+    readonly agent: "claude" | "codex" | "both";
+    readonly skillSet: "core" | "all";
+    readonly workflow: "standard" | "strict";
+    readonly includeHusky: boolean;
+    readonly includeCi: boolean;
+  },
+): string {
+  const commands = [
+    "- `phasegate doctor`",
+    "- `phasegate phasegate:check-ready`",
+    "- `phasegate validate --layer L2 --format human`",
+    "- `phasegate setup:agent --dry-run`",
+    "- `phasegate config:plan --intent l4-strict --dry-run`",
+  ].join("\n");
+  return template
+    .replaceAll("{{PHASEGATE_AGENT}}", options.agent)
+    .replaceAll("{{PHASEGATE_SKILLS_MODE}}", options.skillSet)
+    .replaceAll("{{PHASEGATE_WORKFLOW}}", options.workflow)
+    .replaceAll("{{PHASEGATE_HUSKY_STATE}}", options.includeHusky ? "managed" : "not managed by this setup run")
+    .replaceAll("{{PHASEGATE_CI_STATE}}", options.includeCi ? "managed" : "not managed by this setup run")
+    .replaceAll("{{PHASEGATE_COMMANDS}}", commands)
+    .replaceAll("{{PHASEGATE_SKILLS}}", options.skillSet === "core" ? "- core skills" : "- all bundled skills")
+    .replaceAll("{{PHASEGATE_PRESETS}}", "- `minimal`\n- `standard`\n- `full`\n- `custom`")
+    .replaceAll("{{PHASEGATE_USER_SECTION}}", "Project-specific agent instructions go here.");
+}
+
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -192,6 +242,9 @@ export class RunInstallUseCase {
     const includeCodex = input.includeCodex ?? true;
     const includeHusky = input.includeHusky ?? true;
     const includeCi = input.includeCi ?? true;
+    const skillSet = input.skillSet ?? "all";
+    const workflow = input.workflow ?? "standard";
+    const agent = input.agent ?? (includeClaude && includeCodex ? "both" : includeCodex ? "codex" : "claude");
     const targets = this.createTargets({ includeClaude, includeCodex, includeHusky, includeCi });
     const existingManifest = await this.manifestRepository.load(input.projectRoot);
     const baseManifest = existingManifest ?? DeploymentManifest.create(input.phasegateVersion);
@@ -205,7 +258,10 @@ export class RunInstallUseCase {
     for (const target of targets) {
       const absolutePath = join(input.projectRoot, target.path);
       const before = await readTextOrNull(absolutePath);
-      const template = await readFile(join(input.harnessRoot, target.templatePath), "utf8");
+      const rawTemplate = await readFile(join(input.harnessRoot, target.templatePath), "utf8");
+      const template = target.strategy === "markdown-managed"
+        ? renderAgentContextTemplate(rawTemplate, { agent, skillSet, workflow, includeHusky, includeCi })
+        : rawTemplate;
       const repairMode = this.repairMode(target, before);
       const next = this.merge(target, before, template, input.phasegateVersion);
       const didChange = before !== next;
@@ -300,10 +356,26 @@ export class RunInstallUseCase {
   }): readonly InstallTarget[] {
     return [
       ...(options.includeClaude
-        ? [{ path: ".claude/settings.json", strategy: "json" as const, templatePath: "templates/.claude/settings.json" }]
+        ? [
+            { path: ".claude/settings.json", strategy: "json" as const, templatePath: "templates/.claude/settings.json" },
+            {
+              path: "CLAUDE.md",
+              strategy: "markdown-managed" as const,
+              templatePath: "docs/templates/agent-context/CLAUDE.md.template.md",
+              block: { start: MARKDOWN_BEGIN, end: MARKDOWN_END, content: "phasegate CLAUDE.md managed section" },
+            },
+          ]
         : []),
       ...(options.includeCodex
-        ? [{ path: ".codex/hooks.json", strategy: "json" as const, templatePath: "templates/.codex/hooks.json" }]
+        ? [
+            { path: ".codex/hooks.json", strategy: "json" as const, templatePath: "templates/.codex/hooks.json" },
+            {
+              path: "AGENTS.md",
+              strategy: "markdown-managed" as const,
+              templatePath: "docs/templates/agent-context/AGENTS.md.template.md",
+              block: { start: MARKDOWN_BEGIN, end: MARKDOWN_END, content: "phasegate AGENTS.md managed section" },
+            },
+          ]
         : []),
       ...(options.includeHusky
         ? [
@@ -346,6 +418,7 @@ export class RunInstallUseCase {
   private repairMode(target: InstallTarget, before: string | null): RepairMode {
     if (target.strategy === "shell") return shellRepairMode(before);
     if (target.strategy === "json") return jsonRepairMode(before);
+    if (target.strategy === "markdown-managed") return "mechanical";
     return "mechanical";
   }
 
@@ -358,6 +431,7 @@ export class RunInstallUseCase {
   private merge(target: InstallTarget, before: string | null, template: string, version: string): string {
     if (target.strategy === "yaml-add") return before ?? template;
     if (target.strategy === "shell") return mergeShell(before, template);
+    if (target.strategy === "markdown-managed") return mergeManagedMarkdown(before, template);
     if (target.strategy === "package-json") {
       const existing = before === null ? {} : (JSON.parse(before) as unknown);
       const merged = mergePackageJson(isRecord(existing) ? existing : {}, version || PHASEGATE_SCRIPT_VERSION);

package/scripts/harness/installation/application/usecases/run-reconcile.ts

@@ -1,6 +1,7 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-148
+// @work-item-id WI-174
 
 import { access, chmod, copyFile, lstat, mkdir, readFile, readlink, symlink, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
@@ -12,7 +13,7 @@ import type { HashCalculatorPort } from "../ports/hash-calculator-port.js";
 import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
 
 type ReconcileAction = "missing-manifest" | "update" | "add" | "link" | "skip" | "refuse";
-type StrategyType = "json" | "shell" | "yaml-add" | "package-json" | "symlink" | "unknown";
+type StrategyType = "json" | "shell" | "yaml-add" | "package-json" | "markdown-managed" | "symlink" | "unknown";
 
 export interface ReconcilePlanItem {
   readonly path: string;
@@ -52,6 +53,8 @@ interface ReconcileTarget {
 const SKILL_HINT = "invoke /phasegate-config-doctor";
 const SHELL_BEGIN = "# === phasegate managed (BEGIN) ===";
 const SHELL_END = "# === phasegate managed (END) ===";
+const MARKDOWN_BEGIN = "<!-- phasegate:managed-section:start -->";
+const MARKDOWN_END = "<!-- phasegate:managed-section:end -->";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -136,6 +139,41 @@ function reconcileShell(existing: string | null, incoming: string): string {
   return `${existing.replace(/\s*$/, "\n\n")}${incomingBlock}\n`;
 }
 
+function managedMarkdownBlock(content: string): string {
+  const start = content.indexOf(MARKDOWN_BEGIN);
+  const end = content.indexOf(MARKDOWN_END);
+  if (start === -1 || end === -1 || end < start) return content.trim();
+  return content.slice(start, end + MARKDOWN_END.length).trim();
+}
+
+function reconcileManagedMarkdown(existing: string | null, incoming: string): string {
+  const block = managedMarkdownBlock(incoming);
+  if (existing === null || existing.trim().length === 0) return `${incoming.trim()}\n`;
+  const pattern = new RegExp(`${escapeRegExp(MARKDOWN_BEGIN)}[\\s\\S]*?${escapeRegExp(MARKDOWN_END)}`);
+  if (pattern.test(existing)) return existing.replace(pattern, block).replace(/\s*$/, "\n");
+  return `${block}\n\n${existing.replace(/\s*$/, "\n")}`;
+}
+
+function renderAgentContextTemplate(template: string): string {
+  const commands = [
+    "- `phasegate doctor`",
+    "- `phasegate phasegate:check-ready`",
+    "- `phasegate validate --layer L2 --format human`",
+    "- `phasegate setup:agent --dry-run`",
+    "- `phasegate config:plan --intent l4-strict --dry-run`",
+  ].join("\n");
+  return template
+    .replaceAll("{{PHASEGATE_AGENT}}", "both")
+    .replaceAll("{{PHASEGATE_SKILLS_MODE}}", "all")
+    .replaceAll("{{PHASEGATE_WORKFLOW}}", "standard")
+    .replaceAll("{{PHASEGATE_HUSKY_STATE}}", "managed")
+    .replaceAll("{{PHASEGATE_CI_STATE}}", "managed")
+    .replaceAll("{{PHASEGATE_COMMANDS}}", commands)
+    .replaceAll("{{PHASEGATE_SKILLS}}", "- all bundled skills")
+    .replaceAll("{{PHASEGATE_PRESETS}}", "- `minimal`\n- `standard`\n- `full`\n- `custom`")
+    .replaceAll("{{PHASEGATE_USER_SECTION}}", "Project-specific agent instructions go here.");
+}
+
 function reconcilePackageJson(existing: Record<string, unknown>, version: string): Record<string, unknown> {
   const devDependencies = isRecord(existing.devDependencies) ? existing.devDependencies : {};
   const scripts = isRecord(existing.scripts) ? existing.scripts : {};
@@ -259,7 +297,8 @@ export class RunReconcileUseCase {
     if (before === null) return this.planMissingTarget(input, target);
     const currentHash = this.hashCalculator.compute(before);
     const matchesManifest = currentHash.equals(entry.hash);
-    const template = target.templatePath ? await readFile(join(input.harnessRoot, target.templatePath), "utf8") : "";
+    const rawTemplate = target.templatePath ? await readFile(join(input.harnessRoot, target.templatePath), "utf8") : "";
+    const template = target.strategy === "markdown-managed" ? renderAgentContextTemplate(rawTemplate) : rawTemplate;
     const next = entry.mode === "created" && target.strategy !== "package-json"
       ? template
       : this.reconcileContent(target, before, template, input.phasegateVersion);
@@ -290,7 +329,8 @@ export class RunReconcileUseCase {
     if (target.strategy === "symlink") return this.planSymlink(input.projectRoot, target.path);
     const absolutePath = this.resolveProjectPath(input.projectRoot, target.path);
     const before = await readTextOrNull(absolutePath);
-    const template = target.templatePath ? await readFile(join(input.harnessRoot, target.templatePath), "utf8") : "";
+    const rawTemplate = target.templatePath ? await readFile(join(input.harnessRoot, target.templatePath), "utf8") : "";
+    const template = target.strategy === "markdown-managed" ? renderAgentContextTemplate(rawTemplate) : rawTemplate;
     const next = before === null && target.strategy !== "package-json"
       ? template
       : this.reconcileContent(target, before, template, input.phasegateVersion);
@@ -350,6 +390,7 @@ export class RunReconcileUseCase {
   private reconcileContent(target: ReconcileTarget, before: string | null, template: string, version: string): string {
     if (target.strategy === "yaml-add") return template;
     if (target.strategy === "shell") return reconcileShell(before, template);
+    if (target.strategy === "markdown-managed") return reconcileManagedMarkdown(before, template);
     if (target.strategy === "package-json") {
       const existing = before === null ? {} : (JSON.parse(before) as unknown);
       return `${JSON.stringify(reconcilePackageJson(isRecord(existing) ? existing : {}, version), null, 2)}\n`;
@@ -362,7 +403,19 @@ export class RunReconcileUseCase {
   private createTargets(): readonly ReconcileTarget[] {
     return [
       { path: ".claude/settings.json", strategy: "json", templatePath: "templates/.claude/settings.json" },
+      {
+        path: "CLAUDE.md",
+        strategy: "markdown-managed",
+        templatePath: "docs/templates/agent-context/CLAUDE.md.template.md",
+        block: { start: MARKDOWN_BEGIN, end: MARKDOWN_END, content: "phasegate CLAUDE.md managed section" },
+      },
       { path: ".codex/hooks.json", strategy: "json", templatePath: "templates/.codex/hooks.json" },
+      {
+        path: "AGENTS.md",
+        strategy: "markdown-managed",
+        templatePath: "docs/templates/agent-context/AGENTS.md.template.md",
+        block: { start: MARKDOWN_BEGIN, end: MARKDOWN_END, content: "phasegate AGENTS.md managed section" },
+      },
       {
         path: ".husky/pre-commit",
         strategy: "shell",
@@ -401,7 +454,7 @@ export class RunReconcileUseCase {
 
   private managedBlockFor(path: string, strategy: StrategyType): ManagedBlockInput | null {
     if (strategy === "shell") return { start: SHELL_BEGIN, end: SHELL_END, content: `phasegate ${path} managed block` };
-    if (strategy === "json" || strategy === "package-json") {
+    if (strategy === "json" || strategy === "package-json" || strategy === "markdown-managed") {
       return { start: "phasegate structured merge", end: "phasegate structured merge", content: `${strategy}:${path}` };
     }
     return null;

package/scripts/harness/installation/application/usecases/run-uninstall.ts

@@ -1,6 +1,7 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-147
+// @work-item-id WI-174
 
 import { access, copyFile, lstat, mkdir, readFile, readlink, rm, rmdir, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
@@ -10,7 +11,7 @@ import type { HashCalculatorPort } from "../ports/hash-calculator-port.js";
 import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
 
 type UninstallAction = "missing-manifest" | "delete" | "unlink" | "reverse-merge" | "skip" | "refuse";
-type StrategyType = "created" | "json" | "shell" | "package-json" | "symlink" | "yaml-add" | "unknown";
+type StrategyType = "created" | "json" | "shell" | "package-json" | "markdown-managed" | "symlink" | "yaml-add" | "unknown";
 
 export interface UninstallPlanItem {
   readonly path: string;
@@ -42,6 +43,8 @@ export interface RunUninstallResult {
 const SKILL_HINT = "invoke /phasegate-config-doctor";
 const SHELL_BEGIN = "# === phasegate managed (BEGIN) ===";
 const SHELL_END = "# === phasegate managed (END) ===";
+const MARKDOWN_BEGIN = "<!-- phasegate:managed-section:start -->";
+const MARKDOWN_END = "<!-- phasegate:managed-section:end -->";
 const PHASEGATE_SCRIPT_PREFIX = "phasegate:";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -108,6 +111,11 @@ export function reverseShellMerge(currentContent: string): string {
   return currentContent.replace(pattern, "\n").replace(/\n{3,}/g, "\n\n").replace(/\s*$/, "\n").replace(/^\n/, "");
 }
 
+export function reverseManagedMarkdown(currentContent: string): string {
+  const pattern = new RegExp(`\\n?${escapeRegExp(MARKDOWN_BEGIN)}[\\s\\S]*?${escapeRegExp(MARKDOWN_END)}\\n?`);
+  return currentContent.replace(pattern, "\n").replace(/\n{3,}/g, "\n\n").replace(/\s*$/, "\n").replace(/^\n/, "");
+}
+
 export function reversePackageJsonMerge(currentContent: string): string {
   const parsed = JSON.parse(currentContent) as unknown;
   const result = isRecord(parsed) ? { ...parsed } : {};
@@ -300,6 +308,7 @@ export class RunUninstallUseCase {
 
   private async reverseMerged(harnessRoot: string, path: string, currentContent: string, strategy: StrategyType): Promise<string> {
     if (strategy === "shell") return currentContent.includes(SHELL_BEGIN) ? reverseShellMerge(currentContent) : currentContent;
+    if (strategy === "markdown-managed") return currentContent.includes(MARKDOWN_BEGIN) ? reverseManagedMarkdown(currentContent) : currentContent;
     if (strategy === "package-json") return reversePackageJsonMerge(currentContent);
     if (strategy === "json") return reverseJsonMerge(currentContent, await readFile(join(harnessRoot, this.templateFor(path)), "utf8"));
     throw new Error(`Unsupported merged strategy: ${strategy}`);
@@ -309,6 +318,7 @@ export class RunUninstallUseCase {
     if (mode === "symlink") return "symlink";
     if (mode === "created") return path.endsWith(".yml") || path.endsWith(".yaml") ? "yaml-add" : "created";
     if (path === "package.json") return "package-json";
+    if (path === "AGENTS.md" || path === "CLAUDE.md") return "markdown-managed";
     if (path.endsWith(".json")) return "json";
     if (path.startsWith(".husky/")) return "shell";
     return "unknown";
@@ -317,6 +327,8 @@ export class RunUninstallUseCase {
   private templateFor(path: string): string {
     if (path === ".claude/settings.json") return "templates/.claude/settings.json";
     if (path === ".codex/hooks.json") return "templates/.codex/hooks.json";
+    if (path === "CLAUDE.md") return "docs/templates/agent-context/CLAUDE.md.template.md";
+    if (path === "AGENTS.md") return "docs/templates/agent-context/AGENTS.md.template.md";
     throw new Error(`No template for ${path}`);
   }
 

package/scripts/harness/installation/presentation/cli/install-handler.ts

@@ -12,6 +12,13 @@ export interface InstallHandlerInput {
   readonly apply: boolean;
   readonly force: boolean;
   readonly json: boolean;
+  readonly includeClaude?: boolean;
+  readonly includeCodex?: boolean;
+  readonly includeHusky?: boolean;
+  readonly includeCi?: boolean;
+  readonly skillSet?: "core" | "all";
+  readonly workflow?: "standard" | "strict";
+  readonly agent?: "claude" | "codex" | "both";
 }
 
 export interface InstallHandlerResult {

package/scripts/harness/main.ts

@@ -3,6 +3,7 @@
  * @layer presentation
  * @work-item-id WI-090 / WI-091
  * @work-item-id WI-113 / WI-142
+ * @work-item-id WI-171 / WI-172 / WI-173
  *
  * Phasegate CLI エントリポイント。
  * 各Unitの Composition Root からハンドラーを取得し、コマンドに応じてディスパッチする。
@@ -155,6 +156,8 @@ Setup:
   install                      Install phasegate managed files (--dry-run|--apply, --force)
   uninstall                    Uninstall phasegate managed files (--dry-run|--apply, --force)
   reconcile                    Reconcile phasegate managed files (--dry-run|--apply, --force)
+  setup:agent                  Diagnose repo setup and produce/apply an agent-readable setup plan
+  config:plan                  Produce an agent-readable configuration change plan
 
 Commands:
   enable-feature <name>        Enable a harness feature
@@ -193,6 +196,8 @@ Commands:
   ci:auto-refresh-agent-context Refresh AGENTS.md / CLAUDE.md (--dry-run, --apply, --json)
   refresh-claude-md            Refresh CLAUDE.md standard sections (--dry-run, --apply, --json)
   p2:check-agent-context       Check AGENTS.md / CLAUDE.md freshness (--threshold-days <n>, --json)
+  setup:agent                  Plan agent-driven setup (--intent <minimal|recommended|strict|ci-only|agent-hooks|retrofit>, --agent <claude|codex|both>, --dry-run|--apply, --json)
+  config:plan                  Plan safe config changes (--intent <l4-strict|codex-hooks|ci-fail-on-warning|baseline-reset|quick-mode-strict>, --dry-run, --json)
   ci:check-repetition          Check error repetition (--code <errorCode>, --reset, --json)
   baseline                     Create retrofit baseline snapshot (--dry-run, --force, --paths <glob,glob,...>, --json)
   scaffold-design              Scaffold a design doc (--unit <id>, --phase <logical|domain|uiux|unit-test|it-test>, --force, --json)
@@ -482,8 +487,38 @@ Options:
   --dry-run                       Preview target actions without writing (default)
   --apply                         Write merge results and manifest
   --force                         Force ai-assisted/manual targets after backing up existing files
+  --agent <claude|codex|both>     Agent context and hook targets (default: both)
+  --skills <core|all>             Rendered agent context skill mode (default: all)
+  --workflow <standard|strict>    Rendered agent context workflow mode (default: standard)
+  --with-husky                    Include Husky hook targets
+  --with-ci                       Include GitHub Actions target
   --json                          Output machine-readable JSON
   --help, -h                      Show this help`,
+  "setup:agent": `Usage: phasegate setup:agent [options]
+
+Diagnose repository setup and produce an agent-readable setup plan.
+
+Options:
+  --intent <minimal|recommended|strict|ci-only|agent-hooks|retrofit>
+  --agent <claude|codex|both>
+  --workflow <standard|strict>
+  --with-husky
+  --with-ci
+  --dry-run
+  --apply
+  --json
+  --help, -h                      Show this help`,
+  "config:plan": `Usage: phasegate config:plan --intent <intent> [options]
+
+Produce an agent-readable configuration change plan.
+
+Intents:
+  l4-strict, codex-hooks, ci-fail-on-warning, baseline-reset, quick-mode-strict
+
+Options:
+  --dry-run
+  --json
+  --help, -h                      Show this help`,
   reconcile: `Usage: phasegate reconcile [options]
 
 Reconcile PhaseGate-managed files with the current bundled templates.
@@ -685,6 +720,9 @@ function parseCoverageThreshold(raw: string | undefined): number {
 }
 
 type InitPhasePreset = "full" | "standard" | "minimal" | "custom";
+type AgentTarget = "claude" | "codex" | "both";
+type SetupIntent = "minimal" | "recommended" | "strict" | "ci-only" | "agent-hooks" | "retrofit";
+type ConfigChangeIntent = "l4-strict" | "codex-hooks" | "ci-fail-on-warning" | "baseline-reset" | "quick-mode-strict";
 
 function parseInitPhasePreset(value: string | undefined): InitPhasePreset | undefined {
   if (value === undefined) return undefined;
@@ -694,6 +732,149 @@ function parseInitPhasePreset(value: string | undefined): InitPhasePreset | unde
   return undefined;
 }
 
+function parseAgentTarget(value: string | undefined, fallback: AgentTarget = "both"): AgentTarget {
+  if (value === "claude" || value === "codex" || value === "both") return value;
+  return fallback;
+}
+
+function parseSetupIntent(value: string | undefined): SetupIntent {
+  if (
+    value === "minimal" ||
+    value === "recommended" ||
+    value === "strict" ||
+    value === "ci-only" ||
+    value === "agent-hooks" ||
+    value === "retrofit"
+  ) {
+    return value;
+  }
+  return "recommended";
+}
+
+function parseConfigChangeIntent(value: string | undefined): ConfigChangeIntent {
+  if (
+    value === "l4-strict" ||
+    value === "codex-hooks" ||
+    value === "ci-fail-on-warning" ||
+    value === "baseline-reset" ||
+    value === "quick-mode-strict"
+  ) {
+    return value;
+  }
+  return "l4-strict";
+}
+
+async function projectFileExists(rootDir: string, relativePath: string): Promise<boolean> {
+  try {
+    await fsReadFile(join(rootDir, relativePath));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function buildAgentSetupPlan(rootDir: string, input: {
+  readonly intent: SetupIntent;
+  readonly agent: AgentTarget;
+  readonly withHusky: boolean;
+  readonly withCi: boolean;
+  readonly workflow: WorkflowMode;
+}) {
+  const checks = {
+    packageJson: await projectFileExists(rootDir, "package.json"),
+    phasegateConfig: await projectFileExists(rootDir, "phasegate.config.json"),
+    claudeSettings: await projectFileExists(rootDir, ".claude/settings.json"),
+    codexHooks: await projectFileExists(rootDir, ".codex/hooks.json"),
+    agentsMd: await projectFileExists(rootDir, "AGENTS.md"),
+    claudeMd: await projectFileExists(rootDir, "CLAUDE.md"),
+    huskyPreCommit: await projectFileExists(rootDir, ".husky/pre-commit"),
+    ciWorkflow: await projectFileExists(rootDir, ".github/workflows/phasegate-aidlc-gate.yml"),
+  };
+  const includeClaude = input.agent === "claude" || input.agent === "both";
+  const includeCodex = input.agent === "codex" || input.agent === "both";
+  const changes = [
+    !checks.packageJson ? "Add phasegate devDependency and phasegate scripts to package.json." : "Keep existing package.json and merge missing phasegate scripts only.",
+    !checks.phasegateConfig ? `Create phasegate.config.json for ${input.workflow} workflow.` : "Keep existing phasegate.config.json; review config:plan before changing policy.",
+    includeClaude ? "Create or refresh .claude/settings.json and CLAUDE.md managed section." : null,
+    includeCodex ? "Create or refresh .codex/hooks.json and AGENTS.md managed section." : null,
+    input.withHusky ? "Create or refresh Husky pre-commit, commit-msg, and pre-push backstops." : "Leave Husky hooks unmanaged in this setup run.",
+    input.withCi ? "Create or refresh GitHub Actions PhaseGate workflow." : "Leave CI workflow unmanaged in this setup run.",
+  ].filter((item): item is string => item !== null);
+  const questions = [
+    input.intent === "recommended" ? "Do you want both Claude and Codex context files, or only the agent you actively use?" : null,
+    input.intent === "retrofit" ? "Should existing hooks/workflows be preserved as user-owned content or migrated into PhaseGate managed blocks?" : null,
+    input.intent === "ci-only" ? "Should local hooks remain disabled while CI enforces the same checks?" : null,
+    input.workflow !== "strict" ? "Do you want strict WI/product reflection enforcement now, or after the first green run?" : null,
+  ].filter((item): item is string => item !== null);
+  return {
+    intent: input.intent,
+    agent: input.agent,
+    detected: checks,
+    questions,
+    changes,
+    risks: [
+      "Existing user content outside PhaseGate managed markers is preserved.",
+      "Manual review is still required when a managed target has complex user edits and --force is not used.",
+    ],
+    rollback: [
+      "Run phasegate uninstall --dry-run to preview reversal.",
+      "Run phasegate uninstall --apply after reviewing the managed targets.",
+      "Backups are written under .phasegate/backups when force is used on changed managed files.",
+    ],
+    validation: [
+      "phasegate doctor",
+      "phasegate phasegate:check-ready",
+      "phasegate validate --layer L2 --format human",
+    ],
+  };
+}
+
+function buildConfigChangePlan(intent: ConfigChangeIntent) {
+  const catalog: Record<ConfigChangeIntent, {
+    readonly targets: readonly string[];
+    readonly commands: readonly string[];
+    readonly validations: readonly string[];
+    readonly risks: readonly string[];
+  }> = {
+    "l4-strict": {
+      targets: ["phasegate.config.json: layers.L4.enabled", "phasegate.config.json: layers.L4.failOnWarning"],
+      commands: ["phasegate validate --layer L4 --fail-on-warning --format human"],
+      validations: ["phasegate phasegate:detect-drift --json", "phasegate phasegate:check-ready"],
+      risks: ["L4 findings may be advisory today but become blocking when fail-on-warning is enabled."],
+    },
+    "codex-hooks": {
+      targets: [".codex/hooks.json", "AGENTS.md", ".codex/skills"],
+      commands: ["phasegate install --agent codex --apply", "codex features enable codex_hooks"],
+      validations: ["phasegate doctor --json", "phasegate phasegate:status --json"],
+      risks: ["Codex apply_patch writes still require the pre-commit backstop for full coverage."],
+    },
+    "ci-fail-on-warning": {
+      targets: [".github/workflows/phasegate-aidlc-gate.yml", "phasegate.config.json"],
+      commands: ["phasegate install --with-ci --apply", "phasegate validate --layer L4 --fail-on-warning"],
+      validations: ["phasegate doctor", "phasegate ci:generate-template --type aidlc-gate --render"],
+      risks: ["Existing warning-only projects may start failing CI after rollout."],
+    },
+    "baseline-reset": {
+      targets: [".phasegate/baseline.json"],
+      commands: ["phasegate baseline --dry-run", "phasegate baseline --force --json"],
+      validations: ["phasegate phasegate:status --json", "phasegate phasegate:check-ready"],
+      risks: ["A reset can hide historical drift if reviewed without the generated diff."],
+    },
+    "quick-mode-strict": {
+      targets: ["phasegate.config.json: quickMode"],
+      commands: ["phasegate check-change-category --paths <changed-files> --format json"],
+      validations: ["phasegate ci-check --quick --dry-run", "phasegate phasegate:check-ready"],
+      risks: ["More changes will require Full Mode validation before commit."],
+    },
+  };
+  return {
+    intent,
+    ...catalog[intent],
+    diffExplanation: "Review the listed targets first, apply through PhaseGate managed commands where possible, then run the validations in order.",
+    rollback: "Use git diff for config changes; use phasegate uninstall/reconcile dry-runs for managed setup targets.",
+  };
+}
+
 type RuleSeverity = "error" | "warning" | "off";
 
 function toRuleSeverity(value: string): RuleSeverity {
@@ -999,6 +1180,9 @@ async function main(): Promise<void> {
           includeCodex: deployCodex,
           includeHusky: withHusky,
           includeCi: withCi,
+          skillSet,
+          workflow,
+          agent,
         });
         console.log(
           `✓ Skills deployed to ${result.targetDir} (${result.deployedSkills.length} skills, set: ${skillSet})`,
@@ -1196,7 +1380,7 @@ async function main(): Promise<void> {
       }
 
       case "install": {
-        const KNOWN_INSTALL_FLAGS = ["--dry-run", "--apply", "--force", "--json"];
+        const KNOWN_INSTALL_FLAGS = ["--dry-run", "--apply", "--force", "--json", "--agent", "--skills", "--workflow", "--with-husky", "--with-ci"];
         const flagError = validateKnownFlags(args, KNOWN_INSTALL_FLAGS);
         if (flagError) {
           console.error(flagError);
@@ -1204,6 +1388,19 @@ async function main(): Promise<void> {
         }
         const apply = hasFlag(args, "--apply");
         const dryRun = hasFlag(args, "--dry-run") || !apply;
+        const agent = parseAgentTarget(parseFlag(args, "--agent"), "both");
+        const skillSetRaw = parseFlag(args, "--skills") ?? "all";
+        if (skillSetRaw !== "core" && skillSetRaw !== "all") {
+          console.error(`Invalid --skills value: "${skillSetRaw}". Use "core" or "all".`);
+          process.exit(2);
+        }
+        const workflowRaw = parseFlag(args, "--workflow");
+        if (workflowRaw !== undefined && workflowRaw !== "standard" && workflowRaw !== "strict") {
+          console.error(`Invalid --workflow value: "${workflowRaw}". Use "standard" or "strict".`);
+          process.exit(2);
+        }
+        const includeClaude = agent === "claude" || agent === "both";
+        const includeCodex = agent === "codex" || agent === "both";
         const mod = createInstallationModule();
         const phasegateVersion = await getHarnessVersion(harnessRoot);
         const result = await mod.installHandler.execute({
@@ -1213,6 +1410,13 @@ async function main(): Promise<void> {
           dryRun,
           apply,
           force: hasFlag(args, "--force"),
+          includeClaude,
+          includeCodex,
+          includeHusky: true,
+          includeCi: true,
+          skillSet: skillSetRaw,
+          workflow: parseWorkflowMode(workflowRaw),
+          agent,
           json,
         });
         console.log(result.stdout);
@@ -1220,6 +1424,94 @@ async function main(): Promise<void> {
         break;
       }
 
+      case "setup:agent": {
+        const KNOWN_SETUP_AGENT_FLAGS = ["--intent", "--agent", "--workflow", "--with-husky", "--with-ci", "--dry-run", "--apply", "--force", "--json"];
+        const flagError = validateKnownFlags(args, KNOWN_SETUP_AGENT_FLAGS);
+        if (flagError) {
+          console.error(flagError);
+          process.exit(2);
+        }
+        const intent = parseSetupIntent(parseFlag(args, "--intent"));
+        const agent = parseAgentTarget(parseFlag(args, "--agent"), "both");
+        const workflow = parseWorkflowMode(parseFlag(args, "--workflow") ?? (intent === "strict" ? "strict" : "standard"));
+        const withCi = hasFlag(args, "--with-ci") || intent === "ci-only" || intent === "strict";
+        const withHusky = hasFlag(args, "--with-husky") || intent === "agent-hooks" || intent === "strict";
+        const plan = await buildAgentSetupPlan(rootDir, { intent, agent, withHusky, withCi, workflow });
+        const apply = hasFlag(args, "--apply");
+        let installResult: unknown = null;
+        let bootstrapResult: unknown = null;
+        if (apply) {
+          const skillResult = await deploySkills(harnessRoot, rootDir, "all");
+          const packageResult = await ensurePhasegatePackageDependency(rootDir, skillResult.version);
+          const configResult = await initHarnessConfig(rootDir, "my-project", workflow === "strict" ? "full" : "standard", {
+            ciEnabled: withCi,
+            workflow,
+          });
+          bootstrapResult = {
+            skillsDeployed: skillResult.deployedSkills.length,
+            packageDependency: packageResult,
+            configCreated: configResult.created,
+          };
+          const mod = createInstallationModule();
+          const phasegateVersion = await getHarnessVersion(harnessRoot);
+          installResult = await mod.runInstallUseCase.execute({
+            projectRoot: rootDir,
+            harnessRoot,
+            phasegateVersion,
+            dryRun: false,
+            apply: true,
+            force: hasFlag(args, "--force"),
+            includeClaude: agent === "claude" || agent === "both",
+            includeCodex: agent === "codex" || agent === "both",
+            includeHusky: withHusky,
+            includeCi: withCi,
+            skillSet: "all",
+            workflow,
+            agent,
+          });
+        }
+        const output = { plan, applied: apply, bootstrapResult, installResult };
+        if (json) {
+          console.log(JSON.stringify(output, null, 2));
+        } else {
+          console.log(`phasegate setup:agent ${apply ? "apply" : "dry-run"} (${intent}, ${agent})`);
+          for (const change of plan.changes) console.log(`- ${change}`);
+          if (plan.questions.length > 0) {
+            console.log("");
+            console.log("Questions:");
+            for (const question of plan.questions) console.log(`- ${question}`);
+          }
+          console.log("");
+          console.log("Validation:");
+          for (const command of plan.validation) console.log(`- ${command}`);
+        }
+        process.exit(0);
+        break;
+      }
+
+      case "config:plan": {
+        const KNOWN_CONFIG_PLAN_FLAGS = ["--intent", "--dry-run", "--json"];
+        const flagError = validateKnownFlags(args, KNOWN_CONFIG_PLAN_FLAGS);
+        if (flagError) {
+          console.error(flagError);
+          process.exit(2);
+        }
+        const plan = buildConfigChangePlan(parseConfigChangeIntent(parseFlag(args, "--intent")));
+        if (json) {
+          console.log(JSON.stringify(plan, null, 2));
+        } else {
+          console.log(`phasegate config:plan (${plan.intent})`);
+          console.log("Targets:");
+          for (const target of plan.targets) console.log(`- ${target}`);
+          console.log("Commands:");
+          for (const command of plan.commands) console.log(`- ${command}`);
+          console.log("Validation:");
+          for (const validation of plan.validations) console.log(`- ${validation}`);
+        }
+        process.exit(0);
+        break;
+      }
+
       case "uninstall": {
         const KNOWN_UNINSTALL_FLAGS = ["--dry-run", "--apply", "--force", "--json"];
         const flagError = validateKnownFlags(args, KNOWN_UNINSTALL_FLAGS);

package/skills/phasegate-config-doctor/SKILL.md

@@ -39,6 +39,7 @@ phasegate を導入した直後の config は単純な default で、実プロ
 | Codex hooks | `.codex/hooks.json` | managed hook JSON と Codex hook 配線確認 |
 | Husky scripts | `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push` | pre-commit backstop と bypass audit の確認 |
 | CI workflows | `.github/workflows/*` | `phasegate-aidlc-gate.yml` や既存 workflow との競合確認 |
+| agent context | `AGENTS.md`, `CLAUDE.md` | PhaseGate managed section、lesson pointer section、user-owned content の境界確認 |
 
 **schema は必要なときだけ Read** (enum 違反疑い時など): `node_modules/phasegate/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json` (or `harness-config-v2.schema.json` if v2)。
 
@@ -131,6 +132,9 @@ product-architect で Unit を作り、いくつかの logical_design を書い
 - reconcile / uninstall が refuse → user modified managed target として扱い、`--force` のリスクと backup path を説明して承認を取る
 - Codex の `codex_hooks` feature flag は user-level setting。project-local `install` では変更されないため、必要なら `codex features enable codex_hooks` を案内
 - Codex native `apply_patch` bypass は hook で完全捕捉できない。`.husky/pre-commit` の `phasegate pre-commit` が backstop になるため、Husky 配線を診断対象に含める
+- 初回 setup / retrofit / CI-only / agent-hooks の判断が曖昧な場合は `npx phasegate setup:agent --dry-run --json` を先に使い、検出済み状態、質問、変更案、rollback、validation を根拠として提案する。<!-- @work-item-id WI-172 -->
+- 「L4 を厳しめにして」「Codex hook を有効にして」「CI で warning を fail にして」などの自然言語依頼は、`npx phasegate config:plan --intent <intent> --dry-run --json` で対象ファイル、コマンド、リスク、検証を確認してから diff を提案する。<!-- @work-item-id WI-173 -->
+- `AGENTS.md` は標準運用ルールの managed section と lesson pointer section を分ける。`ci:auto-refresh-agent-context --apply` は lesson pointers 専用 section を更新し、標準運用ルールや user-owned content を置換してはいけない。<!-- @work-item-id WI-174 -->
 
 ### Step 3: 診断レポート
 

package/skills/phasegate-toolkit-guide/SKILL.md

@@ -123,12 +123,17 @@ docs/guide/                          # phasegate リポジトリ自体 (dogfood)
 - 「.phasegate/manifest.json や hook-skip-events は何？」
 
 **参照先**:
+- 最短導線: `docs/guide/getting-started.md`
+- recipes: `docs/guide/recipes.md`
+- troubleshooting: `docs/guide/troubleshooting.md`
 - 新規導入: `docs/guide/installation.md`
 - 既存プロジェクト導入: `docs/guide/retrofit-adoption.md`
 - setup artifact / doctor finding / legacy artifact: `docs/guide/setup-artifacts.md`
 
 `setup-artifacts.md` は managed target / generated artifact / runtime state / legacy artifact / user-level setting の分類を持つ。`doctor --report-out` は明示 path への出力で、`.phasegate/last-doctor-report.json` は固定生成物ではない点もここを参照する。<!-- @work-item-id WI-153 -->
 
+`setup:agent` は初回 setup / retrofit / CI-only / agent hook 有効化の agent-readable planner、`config:plan` は安全な設定変更 intent planner。質問が「次に何を実行するか」「この変更はどの file/validation に対応するか」に寄っている場合は、これらの guide と CLI を案内する。<!-- @work-item-id WI-171, WI-172, WI-173 -->
+
 ### 8. skill 一覧と使い分け
 
 ユーザー質問例: