Initial commit

skills/dev-guided/references/implementation-session.md

@@ -0,0 +1,92 @@
+# Implementation Session Phase
+
+When materials already exist in the docs folder, start an implementation session to continue the development work.
+
+## Session Flow
+
+1. Load context from existing materials
+2. Enter plan mode and create session plan
+3. Implement according to plan
+4. Update progress and other materials
+
+## 1. Load Context
+
+Read all existing materials in order:
+
+1. **problem_statement.md** - Understand the problem scope
+2. **decisions.md** - Understand what choices have been made
+3. **runbook.md** - Understand how to validate work and when to get feedback
+4. **progress.md** - Understand what has been done and what's outstanding
+
+Additionally, check for existing plan files (plan-1.md, plan-2.md, etc.) to understand previous approaches.
+
+## 2. Create Session Plan
+
+Enter plan mode and create a plan for this implementation session:
+
+**Plan should include:**
+- What will be accomplished in this session
+- Specific steps to take
+- Dependencies between steps
+- Expected validation points from runbook.md
+- Outstanding questions or uncertainties
+
+**Determine session number:**
+- Count existing plan-N.md files
+- Next session number = max(N) + 1
+- If no plan files exist, this is session 1
+
+**After plan is approved by human:**
+- Save plan as `plan-N.md` where N is the session number
+- Proceed with implementation
+
+## 3. Implement According to Plan
+
+Follow the plan created in step 2.
+
+**During implementation:**
+
+- **Respect feedback points:** When reaching a feedback point defined in runbook.md, MUST pause and ask for human input
+- **Document new decisions:** If new unclear aspects arise, update decisions.md and ask for human input
+- **Update runbook if needed:** If build/test/validation steps change, update runbook.md
+- **Follow existing decisions:** Use the choices recorded in decisions.md
+
+**Testing and validation:**
+- Follow the build/test instructions in runbook.md
+- Perform validation steps defined in runbook.md
+- Ensure all tests pass before completing session
+
+## 4. Update Progress
+
+At the end of the session, update progress.md with a new entry:
+
+**Entry format:**
+```markdown
+## Session N (YYYY-MM-DD)
+
+### Accomplished
+- [What was implemented/completed]
+- [Tests that now pass]
+- [Issues that were resolved]
+
+### Outstanding
+- [What still needs to be done]
+- [Known issues or blockers]
+
+### Questions
+- [New unclear aspects that need decisions]
+- [Uncertainties or concerns]
+```
+
+**Also update if needed:**
+- **decisions.md** - If new decisions were made
+- **runbook.md** - If validation steps changed
+
+## Session Completion
+
+After updating all materials:
+1. Verify all changes are recorded in progress.md
+2. Verify any new decisions are in decisions.md
+3. Verify runbook.md is current
+4. Inform human that the session is complete
+5. Summarize what was accomplished and what's next

skills/dev-guided/references/initial-setup.md

@@ -0,0 +1,82 @@
+# Initial Setup Phase
+
+When starting a new development session (no materials exist in the docs folder), guide the human through creating the foundational documents through structured Q&A.
+
+## Phase Flow
+
+1. Create problem_statement.md
+2. Create decisions.md
+3. Create runbook.md
+4. Create empty progress.md
+
+## 1. Problem Statement Creation
+
+**Purpose:** Define what problem is being solved, providing scope without prescribing solution.
+
+**Questions to ask:**
+- "What problem are you trying to solve?"
+- "What is the scope of this work? What's explicitly out of scope?"
+- "What does success look like for this work?"
+- "Are there any constraints or requirements I should know about?"
+
+**Format:** Use the template in `template-problem_statement.md`
+
+**Key principle:** Focus on the WHAT and WHY, not the HOW.
+
+## 2. Decisions Creation
+
+**Purpose:** Explicitly capture human choices on unclear aspects. NO assumptions or defaults.
+
+**Critical rule:** MUST ask about every unclear aspect. MUST NOT assume "sensible defaults" or "de facto standards."
+
+**Areas to probe:**
+- Language/framework choices
+- Library/dependency choices
+- Architectural patterns
+- Data storage approaches
+- Testing strategies
+- Error handling approaches
+- Security considerations
+
+**Questions format:**
+- "Which [language/library/pattern] should be used for X?"
+- "How should Y be handled?"
+- "What approach should be taken for Z?"
+
+**For each unclear aspect:**
+1. Explain why a decision is needed
+2. Present options if helpful (but don't bias toward one)
+3. Ask for the human's choice
+4. Record the decision and rationale in decisions.md
+
+**Format:** Use the template in `template-decisions.md`
+
+**Key principle:** Capture explicit human choices, not assumptions.
+
+## 3. Runbook Creation
+
+**Purpose:** Document how to validate work and when to get feedback during implementation.
+
+**Questions to ask:**
+- "How should this code be built/compiled?"
+- "How should this code be run/tested?"
+- "Are there any other validation steps I should perform?"
+- "At what points during implementation should I pause and ask for your feedback?"
+
+**Format:** Use the template in `template-runbook.md`
+
+**Key sections:**
+- Build instructions
+- Test instructions
+- Feedback points (structured list of when to pause for human input)
+- Other validation steps
+
+**Key principle:** Establish clear validation and feedback loops.
+
+## 4. Progress Initialization
+
+Create an empty progress.md file using the template in `template-progress.md`. This will be populated after the first implementation session.
+
+## Completing Initial Setup
+
+After creating all four files, inform the human that the setup is complete and ask if they want to start the first implementation session now or later.

skills/dev-guided/references/template-decisions.md

@@ -0,0 +1,65 @@
+# Decisions
+
+This document captures explicit human choices on unclear aspects of the implementation. Each decision includes the context, options considered, and the chosen approach with rationale.
+
+## Decision Template
+
+Use this format for each decision:
+
+```markdown
+## [Decision Topic]
+
+**Context:** [Why does this decision need to be made?]
+
+**Options Considered:**
+1. [Option A] - [Brief description]
+2. [Option B] - [Brief description]
+
+**Decision:** [Chosen option]
+
+**Rationale:** [Why this choice was made]
+
+**Date:** YYYY-MM-DD
+```
+
+---
+
+## Example Decisions
+
+### Language Choice
+
+**Context:** Need to choose implementation language for the new service.
+
+**Options Considered:**
+1. Python - Good for rapid development, rich ecosystem
+2. Go - Better performance, strong concurrency support
+3. Rust - Maximum performance and safety
+
+**Decision:** Python
+
+**Rationale:** Team is most familiar with Python, and performance requirements don't justify the learning curve of Go or Rust. We can optimize later if needed.
+
+**Date:** 2025-11-24
+
+---
+
+### Database Storage
+
+**Context:** Need to store user session data.
+
+**Options Considered:**
+1. PostgreSQL - Relational, ACID guarantees
+2. Redis - In-memory, fast but volatile
+3. DynamoDB - Managed NoSQL, scalable
+
+**Decision:** Redis with PostgreSQL backup
+
+**Rationale:** Redis for fast session access, PostgreSQL for persistence. Hybrid approach gives us speed and durability.
+
+**Date:** 2025-11-24
+
+---
+
+## Current Decisions
+
+[Add decisions here as they are made during the development session]

skills/dev-guided/references/template-problem_statement.md

@@ -0,0 +1,30 @@
+# Problem Statement
+
+## Problem
+
+[Describe the problem being solved in 2-4 sentences. Focus on WHAT needs to be accomplished and WHY, not HOW it will be done.]
+
+## Scope
+
+### In Scope
+- [What is included in this work]
+- [Specific features or capabilities to be added]
+
+### Out of Scope
+- [What is explicitly not included]
+- [Future work or related features that won't be addressed]
+
+## Success Criteria
+
+[What does success look like? How will you know this is complete?]
+
+- [Measurable outcome 1]
+- [Measurable outcome 2]
+
+## Constraints
+
+[Any constraints or requirements that must be respected]
+
+- [Technical constraints]
+- [Time or resource constraints]
+- [Compatibility requirements]

skills/dev-guided/references/template-progress.md

@@ -0,0 +1,41 @@
+# Progress
+
+This document tracks the progress of implementation sessions. Each session adds a new entry describing what was accomplished, what's outstanding, and any questions that arose.
+
+---
+
+## Session 1 (YYYY-MM-DD)
+
+### Accomplished
+- [What was implemented or completed]
+- [Tests that now pass]
+- [Issues that were resolved]
+
+### Outstanding
+- [What still needs to be done]
+- [Known issues or blockers]
+
+### Questions
+- [New unclear aspects that need decisions]
+- [Uncertainties or concerns]
+
+---
+
+## Session 2 (YYYY-MM-DD)
+
+### Accomplished
+- [What was implemented or completed]
+- [Tests that now pass]
+- [Issues that were resolved]
+
+### Outstanding
+- [What still needs to be done]
+- [Known issues or blockers]
+
+### Questions
+- [New unclear aspects that need decisions]
+- [Uncertainties or concerns]
+
+---
+
+[Continue adding session entries chronologically]

skills/dev-guided/references/template-runbook.md

@@ -0,0 +1,80 @@
+# Runbook
+
+This document describes how to build, test, and validate the work in this development session, as well as when to pause for human feedback.
+
+## Build Instructions
+
+[How to build/compile the code]
+
+```bash
+# Example:
+npm install
+npm run build
+```
+
+## Test Instructions
+
+[How to run tests]
+
+```bash
+# Example:
+npm test
+npm run test:integration
+```
+
+## Run Instructions
+
+[How to run the application locally for manual testing]
+
+```bash
+# Example:
+npm run dev
+# Then visit http://localhost:3000
+```
+
+## Validation Steps
+
+[Any additional validation steps beyond automated tests]
+
+- [ ] Manual testing checklist item 1
+- [ ] Manual testing checklist item 2
+- [ ] Performance check
+- [ ] Security review
+
+## Feedback Points
+
+These are structured points where the agent must pause and ask for human input during implementation.
+
+### After [specific milestone or step]
+**Purpose:** [Why feedback is needed at this point]
+**Questions to ask:** [What specifically to verify or get approval on]
+
+### Before [specific action]
+**Purpose:** [Why approval is needed before proceeding]
+**Questions to ask:** [What to confirm with human]
+
+### When [specific condition occurs]
+**Purpose:** [Why this situation requires human input]
+**Questions to ask:** [What guidance is needed]
+
+---
+
+## Example Feedback Points
+
+### After implementing core authentication logic
+**Purpose:** Verify the authentication approach matches expectations before building dependent features
+**Questions to ask:**
+- Does the login flow work as expected?
+- Should we add any additional authentication factors?
+
+### Before making database schema changes
+**Purpose:** Schema changes are hard to reverse, need approval
+**Questions to ask:**
+- Review proposed schema changes
+- Confirm migration strategy
+
+### When encountering an unclear requirement
+**Purpose:** Avoid making assumptions about product behavior
+**Questions to ask:**
+- Clarify the expected behavior for [specific scenario]
+- Get decision on [unclear aspect]