zhongwei/gh-anexpn-claude-plugins
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 17:54:56 +08:00
commit 5f5aff96e9
26 changed files with 3398 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

208
skills/dev-guided/SKILL.md Normal file
View File

@@ -0,0 +1,208 @@
---
name: dev-guided
description: Guided development workflow for human-in-the-loop iterative implementation. Use this skill for development work where the human wants to maintain control over key decisions, the problem is exploratory rather than well-defined, or when working incrementally with frequent human feedback. This skill creates problem_statement.md, decisions.md, runbook.md, and progress.md artifacts in a development session folder, then guides iterative implementation sessions where the agent plans work, implements, and records progress.
---
# Guided Development
## Overview
Guided development is a workflow designed for iterative, human-in-the-loop software development. Unlike traditional planning approaches that create detailed upfront plans, this workflow establishes problem boundaries, captures explicit human decisions, and enables incremental implementation with continuous feedback.
**Use this skill when:**
- The problem is exploratory and not fully understood upfront
- Human input is needed for key technical decisions
- Development will proceed iteratively across multiple sessions
- The human wants to maintain control rather than delegate to autonomous execution
## Workflow Decision Tree
When the skill is invoked, determine which phase to enter:
```
Does docs/development/NNN-<name>/ exist with materials?
├─ NO → Initial Setup Phase (create problem_statement, decisions, runbook, progress)
└─ YES → Implementation Session Phase (load context, plan, implement, update progress)
```
## Initial Setup Phase
When no materials exist, guide the human through creating foundational documents via structured Q&A.
### Process
1. **Determine folder location**
- Check for existing development session folders: `docs/development/`
- Determine next number: `NNN` (e.g., 001, 002, etc.)
- Ask human for feature name
- Create folder: `docs/development/NNN-<name>/`
2. **Create problem_statement.md**
- Load the template from `references/template-problem_statement.md`
- Ask questions to understand the problem:
- "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?"
- "Are there any constraints or requirements?"
- Fill in the template with responses
- Save as `problem_statement.md`
3. **Create decisions.md**
- Load the template from `references/template-decisions.md`
- **CRITICAL RULE:** MUST ask about every unclear aspect. MUST NOT assume "sensible defaults" or "de facto standards"
- Probe for decisions on:
- Language/framework choices
- Library/dependency choices
- Architectural patterns
- Data storage approaches
- Testing strategies
- Error handling approaches
- Security considerations
- For each unclear aspect:
- Explain why a decision is needed
- Present options if helpful (without bias)
- Ask for the human's choice
- Record the decision with rationale
- Save as `decisions.md`
4. **Create runbook.md**
- Load the template from `references/template-runbook.md`
- Ask questions:
- "How should this code be built/compiled?"
- "How should this code be run/tested?"
- "Are there any other validation steps?"
- "At what points during implementation should I pause and ask for your feedback?"
- Fill in build, test, run, and validation instructions
- Create structured feedback points
- Save as `runbook.md`
5. **Create empty progress.md**
- Load the template from `references/template-progress.md`
- Create empty file (will be populated after first implementation session)
- Save as `progress.md`
6. **Complete setup**
- Inform human that setup is complete
- Ask if they want to start the first implementation session now or later
- If now, proceed to Implementation Session Phase
### Reference Materials
For detailed guidance on the initial setup phase, read `references/initial-setup.md`.
## Implementation Session Phase
When materials already exist, start an implementation session to continue development work.
### Process
1. **Load context**
- Read `problem_statement.md` to understand the problem scope
- Read `decisions.md` to understand what choices have been made
- Read `runbook.md` to understand validation and feedback points
- Read `progress.md` to understand what's been done and what's outstanding
- Check for existing `plan-N.md` files to understand previous approaches
2. **Determine session number**
- List existing `plan-N.md` files
- Next session number = max(N) + 1
- If no plan files exist, this is session 1
3. **Enter plan mode**
- Based on loaded context, create a plan for this session
- Plan should include:
- What will be accomplished
- Specific steps to take
- Dependencies between steps
- Expected validation points from runbook
- Outstanding questions or uncertainties
- Present plan to human for approval
4. **Save approved plan**
- After human approves the plan, save as `plan-N.md` where N is the session number
- Proceed with implementation
5. **Implement according to plan**
- Follow the approved plan
- **Respect feedback points:** When reaching a feedback point 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
- Perform validation steps from runbook.md
- Ensure all tests pass
6. **Update progress.md**
- Add a new session entry using this 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]
```
7. **Session completion**
- Verify all changes are recorded in progress.md
- Verify any new decisions are in decisions.md
- Verify runbook.md is current
- Inform human that session is complete
- Summarize what was accomplished and what's next
### Reference Materials
For detailed guidance on implementation sessions, read `references/implementation-session.md`.
## Key Principles
1. **No Assumptions**: Never assume "sensible defaults" or "de facto standards". Always ask for explicit human decisions.
2. **Respect Feedback Points**: Feedback points in runbook.md are mandatory pause points. Never skip them.
3. **Living Documents**: decisions.md, runbook.md, and progress.md are living documents that evolve throughout the development session.
4. **Session-Scoped Plans**: Each implementation session gets its own plan file. Plans are ephemeral and session-specific, not long-term roadmaps.
5. **Problem-Focused**: problem_statement.md defines the problem and scope, not the solution. It provides boundaries, not prescriptions.
## Example Usage
**Starting new work:**
```
Human: "I want to add OAuth authentication to the app"
Agent: [Invokes dev-guided skill]
Agent: [Creates docs/development/001-oauth-auth/ folder]
Agent: [Guides through creating problem_statement, decisions, runbook, progress]
Agent: "Setup complete. Ready to start first implementation session?"
```
**Continuing existing work:**
```
Human: "Continue working on OAuth" [in directory with existing materials]
Agent: [Invokes dev-guided skill]
Agent: [Loads problem_statement, decisions, runbook, progress]
Agent: [Enters plan mode]
Agent: "Based on progress, I plan to implement token storage. Here's my plan..."
Agent: [After approval, saves as plan-2.md and implements]
Agent: [Updates progress.md with session 2 summary]
```
## Resources
This skill includes reference materials with detailed phase guidance and templates:
### references/
- `initial-setup.md` - Detailed guidance for the initial setup phase
- `implementation-session.md` - Detailed guidance for implementation sessions
- `template-problem_statement.md` - Template for problem statements
- `template-decisions.md` - Template for decisions with examples
- `template-runbook.md` - Template for runbook with feedback point examples
- `template-progress.md` - Template for progress tracking

92
skills/dev-guided/references/implementation-session.md Normal file
View File

@@ -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

82
skills/dev-guided/references/initial-setup.md Normal file
View File

@@ -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.

65
skills/dev-guided/references/template-decisions.md Normal file
View File

@@ -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]

30
skills/dev-guided/references/template-problem_statement.md Normal file
View File

@@ -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]

41
skills/dev-guided/references/template-progress.md Normal file
View File

@@ -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]

80
skills/dev-guided/references/template-runbook.md Normal file
View File

@@ -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]