Refactor documentation structure by renaming 'plans' directory to 'document' across various skills and templates. Update references in README and skill files to reflect the new directory structure for improved clarity and organization.

.cursor/skills/autopilot/SKILL.md

@@ -26,7 +26,7 @@ Auto-chaining execution engine that drives the full BUILD → SHIP workflow. Det
 - **Delegate, don't duplicate**: read and execute each sub-skill's SKILL.md; never inline their logic here
 - **Sound on pause**: follow `.cursor/rules/human-input-sound.mdc` — play a notification sound before every pause that requires human input
 - **Minimize interruptions**: only ask the user when the decision genuinely cannot be resolved automatically
-- **Jira MCP required**: steps that create Jira artifacts (Plan Step 6, Decompose) must have authenticated Jira MCP — never skip or substitute with local files
+- **Jira MCP recommended**: steps that create Jira artifacts (Plan Step 6, Decompose) should have authenticated Jira MCP — if unavailable, offer user the choice to continue with local-only task tracking
 
 ## Jira MCP Authentication
 
@@ -45,22 +45,26 @@ Before entering **Step 2 (Plan)** or **Step 3 (Decompose)** for the first time,
 
 1. Call `mcp_auth` on the Jira MCP server
 2. If authentication succeeds → proceed normally
-3. If the user **skips** authentication → **STOP**. Present using Choose format:
+3. If the user **skips** or authentication fails → present using Choose format:
 
 ```
 ══════════════════════════════════════
- BLOCKER: Jira MCP authentication required
+ Jira MCP authentication failed
 ══════════════════════════════════════
- A) Authenticate now (retry mcp_auth)
- B) Pause autopilot — resume after configuring Jira MCP
+ A) Retry authentication (retry mcp_auth)
+ B) Continue without Jira (tasks saved locally only)
 ══════════════════════════════════════
- Note: Jira integration is mandatory. Plan and Decompose
- steps create epics and tasks that drive implementation.
- Local-only workarounds are not acceptable.
+ Recommendation: A — Jira IDs drive task referencing,
+ dependency tracking, and implementation batching.
+ Without Jira, task files use numeric prefixes instead.
 ══════════════════════════════════════
 ```
 
-Do NOT offer a "skip Jira" or "save locally" option. The workflow depends on Jira IDs for task referencing, dependency tracking, and implementation batching.
+If user picks **B** (continue without Jira):
+- Set a flag in the state file: `jira_enabled: false`
+- All skills that would create Jira tickets instead save metadata locally in the task/epic files with `Jira: pending` status
+- Task files keep numeric prefixes (e.g., `01_initial_structure.md`) instead of Jira ID prefixes
+- The workflow proceeds normally in all other respects
 
 ### Re-Authentication
 
@@ -182,7 +186,7 @@ notes: [any context for next session, e.g. "User asked to revisit risk assessmen
 1. **Create** the state file on the very first autopilot invocation (after state detection determines Step 0)
 2. **Update** the state file after every step completion, every session boundary, and every BLOCKING gate confirmation
 3. **Read** the state file as the first action on every invocation — before folder scanning
-4. **Cross-check**: after reading the state file, verify against actual `_docs/` folder contents. If they disagree (e.g., state file says Step 2 but `_docs/02_plans/architecture.md` already exists), trust the folder structure and update the state file to match
+4. **Cross-check**: after reading the state file, verify against actual `_docs/` folder contents. If they disagree (e.g., state file says Step 2 but `_docs/02_document/architecture.md` already exists), trust the folder structure and update the state file to match
 5. **Never delete** the state file. It accumulates history across the entire project lifecycle
 
 ## Execution Entry Point
@@ -213,6 +217,29 @@ Scan `_docs/` to determine the current workflow position. Check rules in order
 
 ### Detection Rules
 
+**Pre-Step — Existing Codebase Detection**
+Condition: `_docs/` does not exist AND the workspace contains source code files (e.g., `*.py`, `*.cs`, `*.rs`, `*.ts`, `src/`, `Cargo.toml`, `*.csproj`, `package.json`)
+
+Action: An existing codebase without documentation was detected. Present using Choose format:
+
+```
+══════════════════════════════════════
+ DECISION REQUIRED: Existing codebase detected
+══════════════════════════════════════
+ A) Start fresh — define the problem from scratch (normal workflow)
+ B) Document existing codebase first — run /document to reverse-engineer docs, then continue
+══════════════════════════════════════
+ Recommendation: B — the /document skill analyzes your code
+ bottom-up and produces _docs/ artifacts automatically,
+ then you can continue with refactor or the normal workflow.
+══════════════════════════════════════
+```
+
+- If user picks A → proceed to Step 0 (Problem Gathering) as normal
+- If user picks B → read and execute `.cursor/skills/document/SKILL.md`. After document skill completes, re-detect state (the produced `_docs/` artifacts will place the project at Step 2 or later).
+
+---
+
 **Step 0 — Problem Gathering**
 Condition: `_docs/00_problem/` does not exist, OR any of these are missing/empty:
 - `problem.md`
@@ -232,7 +259,7 @@ Action: Read and execute `.cursor/skills/research/SKILL.md` (will auto-detect Mo
 ---
 
 **Step 1b — Research Decision**
-Condition: `_docs/01_solution/` contains `solution_draft*.md` files AND `_docs/01_solution/solution.md` does not exist AND `_docs/02_plans/architecture.md` does not exist
+Condition: `_docs/01_solution/` contains `solution_draft*.md` files AND `_docs/01_solution/solution.md` does not exist AND `_docs/02_document/architecture.md` does not exist
 
 Action: Present the current research state to the user:
 - How many solution drafts exist
@@ -258,18 +285,18 @@ Then present using the **Choose format**:
 ---
 
 **Step 2 — Plan**
-Condition: `_docs/01_solution/` has `solution_draft*.md` files AND `_docs/02_plans/architecture.md` does not exist
+Condition: `_docs/01_solution/` has `solution_draft*.md` files AND `_docs/02_document/architecture.md` does not exist
 
 Action:
 1. The plan skill's Prereq 2 will rename the latest draft to `solution.md` — this is handled by the plan skill itself
 2. Read and execute `.cursor/skills/plan/SKILL.md`
 
-If `_docs/02_plans/` exists but is incomplete (has some artifacts but no `FINAL_report.md`), the plan skill's built-in resumability handles it.
+If `_docs/02_document/` exists but is incomplete (has some artifacts but no `FINAL_report.md`), the plan skill's built-in resumability handles it.
 
 ---
 
 **Step 3 — Decompose**
-Condition: `_docs/02_plans/` contains `architecture.md` AND `_docs/02_plans/components/` has at least one component AND `_docs/02_tasks/` does not exist or has no task files (excluding `_dependencies_table.md`)
+Condition: `_docs/02_document/` contains `architecture.md` AND `_docs/02_document/components/` has at least one component AND `_docs/02_tasks/` does not exist or has no task files (excluding `_dependencies_table.md`)
 
 Action: Read and execute `.cursor/skills/decompose/SKILL.md`
 
@@ -417,6 +444,7 @@ This skill activates when the user wants to:
 **Differentiation**:
 - User wants only research → use `/research` directly
 - User wants only planning → use `/plan` directly
+- User wants to document an existing codebase → use `/document` directly
 - User wants the full guided workflow → use `/autopilot`
 
 ## Methodology Quick Reference