diff --git a/docs/INSTALL.md b/docs/INSTALL.md index b632e12..f819e31 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -136,5 +136,5 @@ If checks fail, **stop** and return: ## Notes -- `docs/plans` / `docs/plan` can be gitignored by design. -- Plan artifacts are intentionally local. +- `create-plan` writes plan artifacts under `ai_plan/`. +- `ai_plan/` should remain gitignored and local-only. diff --git a/skills/create-plan/claude-code/SKILL.md b/skills/create-plan/claude-code/SKILL.md index e363d3e..5cfb707 100644 --- a/skills/create-plan/claude-code/SKILL.md +++ b/skills/create-plan/claude-code/SKILL.md @@ -5,7 +5,7 @@ description: Use when starting a new feature, project, or complex task that need # Create Plan (Claude Code) -Create and maintain a local plan folder under `docs/plans/` (or `docs/plan/` if that repository convention is already in use). +Create and maintain a local plan folder under `ai_plan/` at project root. ## Prerequisite Check (MANDATORY) @@ -37,9 +37,19 @@ If any dependency is missing, stop immediately and return: - Invoke `superpowers:writing-plans`. - Break into milestones and bite-sized stories. -### Phase 5: Generate Plan Files (MANDATORY) +### Phase 5: Initialize Local Plan Workspace (MANDATORY) -Create `docs/plans/YYYY-MM-DD-/` with all files below: +At project root: +1. Ensure `ai_plan/` exists. Create it if missing. +2. Ensure `.gitignore` contains `/ai_plan/`. +3. If `.gitignore` was changed, commit that change immediately (local commit only). + +Recommended commit message: +- `chore(gitignore): ignore ai_plan local planning artifacts` + +### Phase 6: Generate Plan Files (MANDATORY) + +Create `ai_plan/YYYY-MM-DD-/` with all files below: 1. `original-plan.md` - copy of original planner-generated plan. 2. `final-transcript.md` - copy of final planning transcript used to reach approved plan. 3. `milestone-plan.md` - full implementation spec (from template). @@ -48,10 +58,10 @@ Create `docs/plans/YYYY-MM-DD-/` with all files below: Use templates from this skill's `templates/` folder. -### Phase 6: Handoff +### Phase 7: Handoff Always instruct the executing agent: -> Read `docs/plans/YYYY-MM-DD-/continuation-runbook.md` first, then execute from that folder. +> Read `ai_plan/YYYY-MM-DD-/continuation-runbook.md` first, then execute from that folder. Do not rely on planner-private files during implementation. @@ -68,11 +78,14 @@ Do not rely on planner-private files during implementation. ## Gitignore Note -If `docs/plans` or `docs/plan` is gitignored, this is expected. Do not treat inability to commit plan-file updates as a problem. These files are local to the user. +`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates in `ai_plan/` as a problem. ## Verification Checklist -- [ ] Plan directory created under `docs/plans/` (or repo-standard `docs/plan/`) +- [ ] `ai_plan/` exists at project root +- [ ] `.gitignore` includes `/ai_plan/` +- [ ] `.gitignore` ignore-rule commit was created if needed +- [ ] Plan directory created under `ai_plan/YYYY-MM-DD-/` - [ ] `original-plan.md` present - [ ] `final-transcript.md` present - [ ] `milestone-plan.md` present diff --git a/skills/create-plan/claude-code/templates/continuation-runbook.md b/skills/create-plan/claude-code/templates/continuation-runbook.md index 42587c3..013d669 100644 --- a/skills/create-plan/claude-code/templates/continuation-runbook.md +++ b/skills/create-plan/claude-code/templates/continuation-runbook.md @@ -28,7 +28,7 @@ Do NOT reference planner-private files during implementation. ## Mandatory Execution Workflow -Work from this folder (`docs/plans/YYYY-MM-DD-/` or repo-specific `docs/plan/...`) and always follow this order: +Work from this folder (`ai_plan/YYYY-MM-DD-/`) and always follow this order: 1. Read `continuation-runbook.md` first. 2. Execute stories milestone by milestone. @@ -51,7 +51,7 @@ Work from this folder (`docs/plans/YYYY-MM-DD-/` or repo-specific ` ## Git Note -If `docs/plan` or `docs/plans` is gitignored, that is expected and acceptable. Do not treat inability to commit plan-file updates as an error. These files are local planning artifacts. +`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates inside `ai_plan/` as an error. --- diff --git a/skills/create-plan/claude-code/templates/milestone-plan.md b/skills/create-plan/claude-code/templates/milestone-plan.md index c87a861..9c9b7e9 100644 --- a/skills/create-plan/claude-code/templates/milestone-plan.md +++ b/skills/create-plan/claude-code/templates/milestone-plan.md @@ -93,7 +93,7 @@ ## Related Plan Files -This file is part of the plan folder under `docs/plans/` (or `docs/plan/` if that repo convention is used): +This file is part of the plan folder under `ai_plan/`: - `original-plan.md` - Original approved plan (reference for original intent) - `final-transcript.md` - Final planning transcript (reference for rationale/context) - `milestone-plan.md` - This file (full specification) diff --git a/skills/create-plan/codex/SKILL.md b/skills/create-plan/codex/SKILL.md index f2db2d1..e92d545 100644 --- a/skills/create-plan/codex/SKILL.md +++ b/skills/create-plan/codex/SKILL.md @@ -5,7 +5,7 @@ description: Use when starting a new feature, project, or complex task that need # Create Plan (Codex) -Create and maintain a local plan folder under `docs/plans/` (or `docs/plan/` if that repository convention is already in use). +Create and maintain a local plan folder under `ai_plan/` at project root. ## Prerequisite Check (MANDATORY) @@ -40,9 +40,19 @@ If any dependency is missing, stop immediately and return: - Use writing-plans workflow. - Break into milestones and bite-sized stories. -### Phase 6: Generate Plan Files (MANDATORY) +### Phase 6: Initialize Local Plan Workspace (MANDATORY) -Create `docs/plans/YYYY-MM-DD-/` with all files below: +At project root: +1. Ensure `ai_plan/` exists. Create it if missing. +2. Ensure `.gitignore` contains `/ai_plan/`. +3. If `.gitignore` was changed, commit that change immediately (local commit only). + +Recommended commit message: +- `chore(gitignore): ignore ai_plan local planning artifacts` + +### Phase 7: Generate Plan Files (MANDATORY) + +Create `ai_plan/YYYY-MM-DD-/` with all files below: 1. `original-plan.md` - copy of original planner-generated plan. 2. `final-transcript.md` - copy of final planning transcript used to reach approved plan. 3. `milestone-plan.md` - full implementation spec (from template). @@ -51,10 +61,10 @@ Create `docs/plans/YYYY-MM-DD-/` with all files below: Use templates from this skill's `templates/` folder. -### Phase 7: Handoff +### Phase 8: Handoff Always instruct the executing agent: -> Read `docs/plans/YYYY-MM-DD-/continuation-runbook.md` first, then execute from that folder. +> Read `ai_plan/YYYY-MM-DD-/continuation-runbook.md` first, then execute from that folder. Do not rely on planner-private files during implementation. @@ -71,11 +81,14 @@ Do not rely on planner-private files during implementation. ## Gitignore Note -If `docs/plans` or `docs/plan` is gitignored, this is expected. Do not treat inability to commit plan-file updates as a problem. These files are local to the user. +`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates in `ai_plan/` as a problem. ## Verification Checklist -- [ ] Plan directory created under `docs/plans/` (or repo-standard `docs/plan/`) +- [ ] `ai_plan/` exists at project root +- [ ] `.gitignore` includes `/ai_plan/` +- [ ] `.gitignore` ignore-rule commit was created if needed +- [ ] Plan directory created under `ai_plan/YYYY-MM-DD-/` - [ ] `original-plan.md` present - [ ] `final-transcript.md` present - [ ] `milestone-plan.md` present diff --git a/skills/create-plan/codex/templates/continuation-runbook.md b/skills/create-plan/codex/templates/continuation-runbook.md index 42587c3..013d669 100644 --- a/skills/create-plan/codex/templates/continuation-runbook.md +++ b/skills/create-plan/codex/templates/continuation-runbook.md @@ -28,7 +28,7 @@ Do NOT reference planner-private files during implementation. ## Mandatory Execution Workflow -Work from this folder (`docs/plans/YYYY-MM-DD-/` or repo-specific `docs/plan/...`) and always follow this order: +Work from this folder (`ai_plan/YYYY-MM-DD-/`) and always follow this order: 1. Read `continuation-runbook.md` first. 2. Execute stories milestone by milestone. @@ -51,7 +51,7 @@ Work from this folder (`docs/plans/YYYY-MM-DD-/` or repo-specific ` ## Git Note -If `docs/plan` or `docs/plans` is gitignored, that is expected and acceptable. Do not treat inability to commit plan-file updates as an error. These files are local planning artifacts. +`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates inside `ai_plan/` as an error. --- diff --git a/skills/create-plan/codex/templates/milestone-plan.md b/skills/create-plan/codex/templates/milestone-plan.md index c87a861..9c9b7e9 100644 --- a/skills/create-plan/codex/templates/milestone-plan.md +++ b/skills/create-plan/codex/templates/milestone-plan.md @@ -93,7 +93,7 @@ ## Related Plan Files -This file is part of the plan folder under `docs/plans/` (or `docs/plan/` if that repo convention is used): +This file is part of the plan folder under `ai_plan/`: - `original-plan.md` - Original approved plan (reference for original intent) - `final-transcript.md` - Final planning transcript (reference for rationale/context) - `milestone-plan.md` - This file (full specification) diff --git a/skills/create-plan/opencode/SKILL.md b/skills/create-plan/opencode/SKILL.md index b125af1..ed3df91 100644 --- a/skills/create-plan/opencode/SKILL.md +++ b/skills/create-plan/opencode/SKILL.md @@ -5,7 +5,7 @@ description: Use when starting a new feature, project, or complex task that need # Create Plan (Opencode) -Create and maintain a local plan folder under `docs/plans/` (or `docs/plan/` if that repository convention is already in use). +Create and maintain a local plan folder under `ai_plan/` at project root. ## Prerequisite Check (MANDATORY) @@ -36,9 +36,19 @@ If any dependency is missing, stop immediately and return: ### Phase 4: Plan - Break into milestones and bite-sized stories. -### Phase 5: Generate Plan Files (MANDATORY) +### Phase 5: Initialize Local Plan Workspace (MANDATORY) -Create `docs/plans/YYYY-MM-DD-/` with all files below: +At project root: +1. Ensure `ai_plan/` exists. Create it if missing. +2. Ensure `.gitignore` contains `/ai_plan/`. +3. If `.gitignore` was changed, commit that change immediately (local commit only). + +Recommended commit message: +- `chore(gitignore): ignore ai_plan local planning artifacts` + +### Phase 6: Generate Plan Files (MANDATORY) + +Create `ai_plan/YYYY-MM-DD-/` with all files below: 1. `original-plan.md` - copy of original planner-generated plan. 2. `final-transcript.md` - copy of final planning transcript used to reach approved plan. 3. `milestone-plan.md` - full implementation spec (from template). @@ -47,10 +57,10 @@ Create `docs/plans/YYYY-MM-DD-/` with all files below: Use templates from this skill's `templates/` folder. -### Phase 6: Handoff +### Phase 7: Handoff Always instruct the executing agent: -> Read `docs/plans/YYYY-MM-DD-/continuation-runbook.md` first, then execute from that folder. +> Read `ai_plan/YYYY-MM-DD-/continuation-runbook.md` first, then execute from that folder. Do not rely on planner-private files during implementation. @@ -67,11 +77,14 @@ Do not rely on planner-private files during implementation. ## Gitignore Note -If `docs/plans` or `docs/plan` is gitignored, this is expected. Do not treat inability to commit plan-file updates as a problem. These files are local to the user. +`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates in `ai_plan/` as a problem. ## Verification Checklist -- [ ] Plan directory created under `docs/plans/` (or repo-standard `docs/plan/`) +- [ ] `ai_plan/` exists at project root +- [ ] `.gitignore` includes `/ai_plan/` +- [ ] `.gitignore` ignore-rule commit was created if needed +- [ ] Plan directory created under `ai_plan/YYYY-MM-DD-/` - [ ] `original-plan.md` present - [ ] `final-transcript.md` present - [ ] `milestone-plan.md` present diff --git a/skills/create-plan/opencode/templates/continuation-runbook.md b/skills/create-plan/opencode/templates/continuation-runbook.md index 42587c3..013d669 100644 --- a/skills/create-plan/opencode/templates/continuation-runbook.md +++ b/skills/create-plan/opencode/templates/continuation-runbook.md @@ -28,7 +28,7 @@ Do NOT reference planner-private files during implementation. ## Mandatory Execution Workflow -Work from this folder (`docs/plans/YYYY-MM-DD-/` or repo-specific `docs/plan/...`) and always follow this order: +Work from this folder (`ai_plan/YYYY-MM-DD-/`) and always follow this order: 1. Read `continuation-runbook.md` first. 2. Execute stories milestone by milestone. @@ -51,7 +51,7 @@ Work from this folder (`docs/plans/YYYY-MM-DD-/` or repo-specific ` ## Git Note -If `docs/plan` or `docs/plans` is gitignored, that is expected and acceptable. Do not treat inability to commit plan-file updates as an error. These files are local planning artifacts. +`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates inside `ai_plan/` as an error. --- diff --git a/skills/create-plan/opencode/templates/milestone-plan.md b/skills/create-plan/opencode/templates/milestone-plan.md index c87a861..9c9b7e9 100644 --- a/skills/create-plan/opencode/templates/milestone-plan.md +++ b/skills/create-plan/opencode/templates/milestone-plan.md @@ -93,7 +93,7 @@ ## Related Plan Files -This file is part of the plan folder under `docs/plans/` (or `docs/plan/` if that repo convention is used): +This file is part of the plan folder under `ai_plan/`: - `original-plan.md` - Original approved plan (reference for original intent) - `final-transcript.md` - Final planning transcript (reference for rationale/context) - `milestone-plan.md` - This file (full specification)