jsegov · jsegov · Jan 11, 2026 · Jan 11, 2026 · Jan 11, 2026
diff --git a/README.md b/README.md
@@ -57,7 +57,7 @@ Run `/feature-planning <name>` to go through the complete planning workflow:
 
 The command guides you through 6 phases:
 
-1. **Setup** - Creates `docs/planning/user-authentication/` and extracts codebase context
+1. **Setup** - Creates `.shipspec/planning/user-authentication/` and extracts codebase context
 
 2. **Requirements Gathering** - Interactive Q&A with the PRD Gatherer agent about:
    - The problem you're solving
@@ -93,7 +93,7 @@ The command guides you through 6 phases:
    /productionalize pre-launch
    ```
    This will:
-   - Create `docs/planning/pre-launch/` directory
+   - Create `.shipspec/planning/pre-launch/` directory
    - Detect tech stack and infrastructure
    - Start a guided interview about concerns
 
@@ -115,7 +115,7 @@ The command guides you through 6 phases:
 
 4. **Review Reports**
    ```
-   docs/planning/pre-launch/
+   .shipspec/planning/pre-launch/
    ├── production-signals.md   # Detected tech stack
    ├── production-report.md    # Full analysis report
    └── fix-prompts.md          # Agent-ready fix prompts
@@ -135,13 +135,14 @@ The command guides you through 6 phases:
 After completing the feature planning workflow:
 
 ```
-docs/planning/your-feature/
-├── context.md   # Codebase context and patterns
+.shipspec/planning/your-feature/
 ├── PRD.md       # Product Requirements Document
 ├── SDD.md       # Software Design Document
 └── TASKS.md     # Implementation tasks with agent prompts
 ```
 
+Note: A temporary `context.md` file is created during planning but automatically cleaned up after task generation.
+
 ## Commands
 
 | Command | Description |

diff --git a/agents/design-architect.md b/agents/design-architect.md
@@ -57,7 +57,7 @@ Read the key files you find. Understand:
 
 ### Phase 2: Review the PRD
 
-The PRD should be at `docs/planning/[feature]/PRD.md`. Read it and:
+The PRD should be at `.shipspec/planning/[feature]/PRD.md`. Read it and:
 - List all requirements (REQ-XXX)
 - Identify technical implications of each
 - Note any requirements that conflict with existing patterns
@@ -165,6 +165,6 @@ Structure your design document following the 8-section Atlassian template. Ensur
 ## Handoff
 
 When complete, the design should be saved to:
-`docs/planning/[feature]/SDD.md`
+`.shipspec/planning/[feature]/SDD.md`
 
 The workflow will automatically proceed to generate implementation tasks.
diff --git a/agents/task-planner.md b/agents/task-planner.md
@@ -37,9 +37,9 @@ You are a technical project manager specializing in breaking down features into
 ### Phase 1: Review Inputs
 
 Read the existing planning documents:
-- `docs/planning/[feature]/PRD.md` - Requirements
-- `docs/planning/[feature]/SDD.md` - Technical design
-- `docs/planning/[feature]/context.md` - Codebase context (if exists)
+- `.shipspec/planning/[feature]/PRD.md` - Requirements
+- `.shipspec/planning/[feature]/SDD.md` - Technical design
+- `.shipspec/planning/[feature]/context.md` - Codebase context (if exists)
 
 Extract:
 - All requirements (REQ-XXX)

diff --git a/commands/feature-planning.md b/commands/feature-planning.md
@@ -1,7 +1,7 @@
 ---
 description: Start planning a new feature with AI-assisted PRD generation
 argument-hint: <feature-name>
-allowed-tools: Read, Glob, Grep, Write, Bash(git status), Bash(git log:*), Bash(find:*), Bash(ls:*), Bash(cat:*), Bash(head:*), Bash(mkdir:*), Task
+allowed-tools: Read, Glob, Grep, Write, Bash(git status), Bash(git log:*), Bash(find:*), Bash(ls:*), Bash(cat:*), Bash(head:*), Bash(mkdir:*), Bash(rm:*), Task, AskUserQuestion
 ---
 
 # Feature Planning: $ARGUMENTS
@@ -25,7 +25,7 @@ This command runs through 6 phases:
 Create the planning directory structure:
 
 ```bash
-mkdir -p docs/planning/$ARGUMENTS
+mkdir -p .shipspec/planning/$ARGUMENTS
 ```
 
 ### Extract Codebase Context
@@ -38,7 +38,7 @@ Analyze the current codebase to understand:
 4. **Documentation** - What guidance exists?
 
 Use the codebase-context skill for this analysis. Save findings to:
-`docs/planning/$ARGUMENTS/context.md`
+`.shipspec/planning/$ARGUMENTS/context.md`
 
 ---
 
@@ -65,7 +65,7 @@ When the user indicates requirements are complete, proceed to Phase 3.
 
 Load the context file:
 ```bash
-cat docs/planning/$ARGUMENTS/context.md 2>/dev/null || echo "No context file found"
+cat .shipspec/planning/$ARGUMENTS/context.md 2>/dev/null || echo "No context file found"
 ```
 
 Using the prd-template skill, create a comprehensive PRD with:
@@ -94,23 +94,22 @@ Using the prd-template skill, create a comprehensive PRD with:
 
 6. **Open Questions**
 
-Save the PRD to: `docs/planning/$ARGUMENTS/PRD.md`
+Save the PRD to: `.shipspec/planning/$ARGUMENTS/PRD.md`
 
 ### Review Gate
 
-After generating, tell the user:
+After generating, use the AskUserQuestion tool to get approval:
 
-> "**PRD generated and saved to `docs/planning/$ARGUMENTS/PRD.md`**
->
-> Please review the document.
->
-> Reply with:
-> - **'looks good'** or **'approved'** to continue to technical design
-> - Or describe any changes needed"
+- **Header**: "PRD Review"
+- **Question**: "PRD generated and saved to `.shipspec/planning/$ARGUMENTS/PRD.md`. Please review the document. Would you like to approve it or request changes?"
+- **Options**:
+  - **Approve**: "Continue to technical design phase"
+  - **Request changes**: "I'll describe changes needed"
 
-**WAIT for user approval before proceeding to Phase 4.**
+**WAIT for user response before proceeding.**
 
-If the user requests changes, update the PRD and ask for review again.
+- If **"Approve"** selected: Continue to Phase 4.
+- If **"Request changes"** selected: Ask user to describe the changes, update the PRD, then ask for review again.
 
 ---
 
@@ -139,11 +138,11 @@ When the user indicates technical decisions are complete, proceed to Phase 5.
 ## Phase 5/6: Generate SDD
 
 Load the PRD:
-@docs/planning/$ARGUMENTS/PRD.md
+@.shipspec/planning/$ARGUMENTS/PRD.md
 
 Load context:
 ```bash
-cat docs/planning/$ARGUMENTS/context.md 2>/dev/null || echo "No context file"
+cat .shipspec/planning/$ARGUMENTS/context.md 2>/dev/null || echo "No context file"
 ```
 
 Using the sdd-template skill, create a comprehensive design document with all 8 sections:
@@ -159,28 +158,27 @@ Using the sdd-template skill, create a comprehensive design document with all 8
 
 Ensure every requirement from the PRD is addressed with traceability.
 
-Save the SDD to: `docs/planning/$ARGUMENTS/SDD.md`
+Save the SDD to: `.shipspec/planning/$ARGUMENTS/SDD.md`
 
 ### Review Gate
 
-After generating, tell the user:
+After generating, summarize the key design decisions and use the AskUserQuestion tool to get approval:
 
-> "**SDD generated and saved to `docs/planning/$ARGUMENTS/SDD.md`**
->
-> Key design decisions:
+> **Key design decisions:**
 > - [Decision 1]
 > - [Decision 2]
 > - [Decision 3]
->
-> Please review the technical design.
->
-> Reply with:
-> - **'looks good'** or **'approved'** to generate implementation tasks
-> - Or describe any changes needed"
 
-**WAIT for user approval before proceeding to Phase 6.**
+- **Header**: "SDD Review"
+- **Question**: "SDD generated and saved to `.shipspec/planning/$ARGUMENTS/SDD.md`. Please review the technical design. Would you like to approve it or request changes?"
+- **Options**:
+  - **Approve**: "Continue to generate implementation tasks"
+  - **Request changes**: "I'll describe changes needed"
+
+**WAIT for user response before proceeding.**
 
-If the user requests changes, update the SDD and ask for review again.
+- If **"Approve"** selected: Continue to Phase 6.
+- If **"Request changes"** selected: Ask user to describe the changes, update the SDD, then ask for review again.
 
 ---
 
@@ -189,12 +187,12 @@ If the user requests changes, update the SDD and ask for review again.
 Once the SDD is approved, automatically generate implementation tasks.
 
 Load the planning documents:
-@docs/planning/$ARGUMENTS/PRD.md
-@docs/planning/$ARGUMENTS/SDD.md
+@.shipspec/planning/$ARGUMENTS/PRD.md
+@.shipspec/planning/$ARGUMENTS/SDD.md
 
 Load context:
 ```bash
-cat docs/planning/$ARGUMENTS/context.md 2>/dev/null || echo "No context file"
+cat .shipspec/planning/$ARGUMENTS/context.md 2>/dev/null || echo "No context file"
 ```
 
 Delegate to the `task-planner` subagent to:
@@ -223,7 +221,17 @@ Using the agent-prompts skill, create a comprehensive task list with:
    - Dependencies clearly marked
    - Acceptance criteria
 
-Save the tasks to: `docs/planning/$ARGUMENTS/TASKS.md`
+Save the tasks to: `.shipspec/planning/$ARGUMENTS/TASKS.md`
+
+### Cleanup Temporary Files
+
+After tasks are generated successfully, clean up the temporary context file:
+
+```bash
+rm -f .shipspec/planning/$ARGUMENTS/context.md
+```
+
+The context information is now incorporated into the PRD, SDD, and TASKS.md files.
 
 ---
 
@@ -240,10 +248,9 @@ After all phases complete, provide:
 > - Critical Path: [list]
 >
 > **Generated Documents:**
-> - `docs/planning/$ARGUMENTS/context.md` - Codebase context
-> - `docs/planning/$ARGUMENTS/PRD.md` - Product requirements
-> - `docs/planning/$ARGUMENTS/SDD.md` - Technical design
-> - `docs/planning/$ARGUMENTS/TASKS.md` - Implementation tasks
+> - `.shipspec/planning/$ARGUMENTS/PRD.md` - Product requirements
+> - `.shipspec/planning/$ARGUMENTS/SDD.md` - Technical design
+> - `.shipspec/planning/$ARGUMENTS/TASKS.md` - Implementation tasks
 >
 > **Next Steps:**
 > Run `/implement-next-task` to start implementing the first task.

diff --git a/commands/implement-next-task.md b/commands/implement-next-task.md
@@ -13,7 +13,7 @@ Find and display the next task ready for implementation, verifying any in-progre
 Check that TASKS.md exists:
 ```bash
 echo "=== Checking TASKS.md ==="
-ls -la docs/planning/$ARGUMENTS/TASKS.md 2>/dev/null || echo "TASKS.md NOT FOUND"
+ls -la .shipspec/planning/$ARGUMENTS/TASKS.md 2>/dev/null || echo "TASKS.md NOT FOUND"
 ```
 
 If TASKS.md is not found, tell the user:
@@ -22,7 +22,7 @@ If TASKS.md is not found, tell the user:
 ## Step 2: Load and Parse Tasks
 
 Load the tasks document:
-@docs/planning/$ARGUMENTS/TASKS.md
+@.shipspec/planning/$ARGUMENTS/TASKS.md
 
 Parse the document to extract:
 1. **All tasks** with their IDs, titles, and statuses

diff --git a/commands/productionalize.md b/commands/productionalize.md
@@ -13,7 +13,7 @@ Analyze the codebase for production readiness, identifying security vulnerabilit
 Create the output directory for analysis results:
 
 ```bash
-mkdir -p docs/planning/$ARGUMENTS
+mkdir -p .shipspec/planning/$ARGUMENTS
 ```
 
 ## Step 2: Gather Codebase Signals
@@ -28,7 +28,7 @@ Use the production-signals skill to detect:
 - Security configuration
 - Monitoring and observability
 
-Save signals to: `docs/planning/$ARGUMENTS/production-signals.md`
+Save signals to: `.shipspec/planning/$ARGUMENTS/production-signals.md`
 
 ## Step 3: Gather Production Context
 
@@ -70,7 +70,7 @@ Delegate to the `production-reporter` subagent to generate:
 1. **production-report.md** - Executive summary, findings by category, compliance matrix, remediation roadmap
 2. **fix-prompts.md** - Agent-ready prompts for each finding
 
-Save to: `docs/planning/$ARGUMENTS/`
+Save to: `.shipspec/planning/$ARGUMENTS/`
 
 ## Step 6: Present Results
 
@@ -79,9 +79,9 @@ After report generation, present a summary:
 > **Production Readiness Analysis Complete**
 >
 > **Output files:**
-> - `docs/planning/$ARGUMENTS/production-signals.md` - Detected tech stack and infrastructure
-> - `docs/planning/$ARGUMENTS/production-report.md` - Full analysis report
-> - `docs/planning/$ARGUMENTS/fix-prompts.md` - Agent-ready fix prompts
+> - `.shipspec/planning/$ARGUMENTS/production-signals.md` - Detected tech stack and infrastructure
+> - `.shipspec/planning/$ARGUMENTS/production-report.md` - Full analysis report
+> - `.shipspec/planning/$ARGUMENTS/fix-prompts.md` - Agent-ready fix prompts
 >
 > **Summary:**
 > - Overall Status: [Ready/Ready with Reservations/Not Ready]

diff --git a/skills/codebase-context/SKILL.md b/skills/codebase-context/SKILL.md
@@ -129,10 +129,12 @@ Structure codebase context summaries as:
 ## Integration Notes
 
 This context should be:
-1. Saved to `docs/planning/<feature>/context.md` for reference
+1. Saved to `.shipspec/planning/<feature>/context.md` temporarily during planning
 2. Used by PRD and design document generation
 3. Referenced when creating implementation tasks
 
+**Note:** The context file is automatically cleaned up after task generation completes. The relevant context is incorporated into the PRD, SDD, and TASKS.md files.
+
 ## Common Tech Stack Indicators
 
 | Indicator | Technology |