ワンクリックで
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
メニュー
Use when you have a spec or requirements for a multi-step task, before touching code
USE THIS SKILL whenever a user asks for a comprehensive implementation plan, a full-stack build plan, a UI+backend plan, or says 'create a plan for building X' where X spans multiple phases or systems. Also activate when the user says 'plan this project', 'I need a detailed plan', 'build plan', 'implementation plan', or attaches a mockup/wireframe and asks how to build it. Produces a zero-ambiguity, evidence-gated plan with self-contained per-phase prompts, exhaustive data binding tables, per-phase validation checklists, and a global quality gate. Evidence-gated: before writing phases, verify required artefacts (mockup, data sample, API contract, scaffold inventory); if any BLOCKER is missing, ask for it and wait before proceeding. Dual-mode: generic by default, junai-pipeline only when explicitly requested. Agent-agnostic - any agent with read/search/edit tools can use this skill.
Systematic code change verification — lint, test, type-check, review
Structure freetext ideas, backlog items, or vague requirements into a formal Intent Document that preserves user intent across the entire agent pipeline chain.
Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.
Technical documentation best practices for READMEs, API docs, architecture docs, runbooks, and developer guides. Use when writing or reviewing documentation, creating onboarding guides, or establishing documentation standards.
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
| name | writing-plans |
| context | fork |
| description | Use when you have a spec or requirements for a multi-step task, before touching code |
Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
Announce at start: "I'm using the writing-plans skill to create the implementation plan."
Context: This should be run in a dedicated worktree (created by brainstorming skill).
Save plans to: docs/plans/YYYY-MM-DD-<feature-name>.md
Document metadata: Before creating or updating a plan, apply .github/instructions/document-frontmatter.instructions.md. The YAML frontmatter block must be the first content in the file. New plans require Original Author, Creation Date, and Creating Model; revised plans must preserve those fields and add or update Last Author, Last Updated, and Last Model Used.
Each step is one action (2-5 minutes):
Every plan MUST start with this header (YAML frontmatter first, then title):
---
chain_id: <chain_id>
type: plan
status: current
approval: pending
Original Author: <active author or agent name>
Creation Date: <YYYY-MM-DDTHH:MM:SSZ>
Creating Model: <exact runtime model identifier or display name>
---
# [Feature Name] Implementation Plan
> **For the implementing agent:** Follow this plan task-by-task, executing each step sequentially.
**Goal:** [One sentence describing what this builds]
**Architecture:** [2-3 sentences about approach]
**Tech Stack:** [Key technologies/libraries]
---
⚠️ The YAML frontmatter block (
---delimiters) is required for Orchestrator artefact contract validation. Do NOT use blockquote-style metadata (> **approval:** pending) — it will not be parsed. Preserve the original metadata fields on later edits, and add or updateLast Author,Last Updated, andLast Model Usedwhen the plan is revised. Use full ISO 8601 UTC timestamps forCreation DateandLast Updated.
### Task N: [Component Name]
**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`
**Step 1: Write the failing test**
```python
def test_specific_behavior():
result = function(input)
assert result == expected
Step 2: Run test to verify it fails
Run: pytest tests/path/test.py::test_name -v
Expected: FAIL with "function not defined"
Step 3: Write minimal implementation
def function(input):
return expected
Step 4: Run test to verify it passes
Run: pytest tests/path/test.py::test_name -v
Expected: PASS
Step 5: Commit
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
## Manual Execution Protocol
**Every plan MUST include a Manual Execution Protocol section** at the top (after header, before phases). This tells the user exactly how to run each phase session:
```markdown
## Manual Execution Protocol
For each phase below, follow this workflow:
1. **Open** a new chat session with the agent specified in the phase header
2. **Load skills** listed in the phase's "Skills to load" section
3. **Attach files** listed in the phase's "Files to attach" section
4. **Paste** the self-contained Phase Prompt into the chat
5. **Validate** using the phase's Validation Checklist — every item must pass
6. **Get green light** before moving to the next phase
**Drift rule:** If you find bugs introduced by Phase N, fix them in the SAME session
before starting Phase N+1. Never carry implementation debt forward between phases.
**Dependency sequencing rule:** Write phases in execution order \u2014 every phase's dependencies must appear before that phase in the plan. If Phase 3 requires output from Phase 4, reorder before writing. No forward dependencies.
Every multi-phase plan MUST include a Phase 0 before the implementation phases. Phase 0 is not an implementation phase — it is a ground-truth inventory that prevents agents from making assumptions.
Phase 0 contains four mandatory tables:
### Technology Decisions
| Decision | Choice | Rationale |
|----------|--------|-----------|
| Charting library | Recharts | Tree-shakeable, React-native, typed API |
| Animation | Framer Motion | AnimatePresence for tab transitions, spring physics |
| State management | Zustand | Lightweight, no boilerplate, devtools support |
| ... | ... | ... |
Every technology choice that is NOT already in project-config.md must appear here with a rationale.
### Data Availability
| Feature / Tab | Data Field | Available? | Strategy |
|---------------|-----------|------------|----------|
| Executive Overview | `ceoInsight` | ✅ Full | Live API |
| Product Deep-Dive | `satisfactionScores` | ❌ Empty `{}` | Show empty state: "Coming in future release" |
| Geography | `byGeography` | ⚠️ Partial (was present May-Oct) | Show empty state with explanation |
| ... | ... | ... | ... |
For any data field that may be empty, partial, or absent: document the exact empty state message text.
### Existing Scaffold — DO NOT Recreate
| File | Purpose | Current State |
|------|---------|---------------|
| `frontend/src/api/client.ts` | API client with JWT auth | ✅ Working — build on top |
| `frontend/src/types/nps.ts` | 30+ TypeScript interfaces | ✅ Working — import, don't recreate |
| `frontend/src/components/layout/AppShell.tsx` | App shell | ⚠️ Cold zinc theme — needs warm overhaul |
| ... | ... | ... |
The "Current State" column tells agents what exists and whether to modify or leave it alone.
### Dependencies
**Already installed** (DO NOT reinstall):
- react, react-dom, typescript, vite
- @tanstack/react-query, @tanstack/react-router
- tailwindcss, zustand
**Not yet installed** (install in Phase 1):
- recharts, framer-motion, leaflet, react-leaflet
- d3-force, d3-scale
Every implementation phase MUST use this structure. The sections OUTSIDE the prompt block are for the user (what to prepare before opening a session). The prompt block is for the agent (what to paste into the session).
## Phase N — {Name}
**Agent:** `@{agent-name}`
**Objective:** {One sentence describing what this phase builds}
### Skills to load
- `.github/skills/{path}/SKILL.md` — {why}
- `.github/skills/{path}/SKILL.md` — {why}
### Instructions to follow
- `.github/instructions/{name}.instructions.md`
- `.github/instructions/{name}.instructions.md`
### Files to attach
- `path/to/file.ext` — {why this file is needed}
- `path/to/file.ext` (from Phase N-1)
- `.github/plans/{this-plan}.md` (this file)
### Phase Prompt
\`\`\`
{Self-contained prompt — copy-paste ready. 30-60 lines.
References plan sections for detail. Does NOT duplicate code blocks.
Includes PRINCIPLES, SKILLS TO READ, IMPORTANT warnings, and numbered deliverable list.}
\`\`\`
### What to build
#### N.1 {Deliverable Name}
**File:** `exact/path/to/file.ext`
{Component interface / function signature}
**Data binding:**
- Uses `data.field.path` for {purpose}
- Uses `data.other.field` for {purpose}
**Behavior:**
- {Specific interactive behavior}
- {Animation spec with exact values}
**Empty state:** When `data.field` is `{}` or `[]`:
> "{Exact message text to display}"
**IMPORTANT:** {Trap-specific warning — e.g., "DO NOT recreate api/client.ts",
"field uses snake_case in BOTH API and TS types — no transformation needed"}
#### N.2 {Next Deliverable}
...
### Validation Checklist — Phase N complete when
- [ ] `npm run build` succeeds (or equivalent build command)
- [ ] {Specific behavioral criterion — e.g., "KpiFlipCard flip animation works independently on each card"}
- [ ] {Data binding criterion — e.g., "NpsSummaryTable renders 5 rows with correct data from surveys + trend"}
- [ ] {Visual criterion — e.g., "Dark mode: all components render correctly with soft dark tokens"}
- [ ] {Integration criterion — e.g., "Row click switches to Tab 2 and scrolls to chart"}
- [ ] Zero hardcoded data — all from props/hooks
- [ ] Zero hardcoded colors — all from CSS vars or constants
Data binding is mandatory for UI components. Every component spec must list the exact JSON field paths it consumes (e.g., surveys.{product}.nps, trend.historicalNPS.byProduct.{product}). This eliminates the #1 implementer failure mode: guessing which field to bind.
Empty state specs are mandatory. For every data field that might be empty, specify the exact message text. Do NOT say "show appropriate empty state" — write the message.
IMPORTANT warnings for traps. If a file already exists and must NOT be recreated, say so. If a field uses unexpected casing (snake_case where camelCase is expected), warn explicitly. These prevent the most common implementation errors.
Complete code blocks when the component is foundational. For theme files, config files, utility functions, and CSS — include the full source code in the plan. For application components — specify interface, behavior, and data binding; let the agent write the implementation.
═══ PROMPT START / ═══ PROMPT END markers````) for the outer prompt block so nested code blocks render correctlyRun this AFTER all phases are written, BEFORE finalizing the plan.
Walk through every FR, NFR, risk, and design decision from ALL input documents. For each, verify it maps to a specific, actionable plan step. Output a traceability matrix:
## Source Document Traceability
| Requirement | Source | Plan Phase/Step | Status |
|-------------|--------|-----------------|--------|
| FR-101 | PRD §3.1 | Phase 1, Step 2 | ✅ Covered |
| NFR-208 | PRD §4.2 | Phase 5, Step 1 | ✅ Covered |
| Risk-003 | Arch §9 | Phase 3, Step 3 | ✅ Covered |
| ALT-002 | Arch §7.4 | N/A | ⚠️ Out of Scope — rationale: deferred to v2 |
Rules:
Every phase/step MUST include a ready-to-use prompt block. This is non-negotiable because plans are executed across multiple sessions by different agents.
CRITICAL: Use 4-backtick fences (
````) for the outer prompt block so nested code blocks (yaml, python, etc.) inside the prompt render correctly. Add═══ PROMPT STARTand═══ PROMPT ENDmarkers so users can clearly see where to copy from/to.
### Ready-to-Use Prompt (Phase N — Step M)
> **How to use:** Copy the prompt block below (between ═══ START and ═══ END markers) into a new chat session. **Include all code blocks** — they're context for the agent, not for you to apply manually.
> **Agent:** `@{agent-name}` (see `.github/agents/{agent-name}.agent.md`)
> **Skills to load:** `.github/skills/{skill-path}/SKILL.md`
> **Instructions (auto-applied):** `{instruction1}.instructions.md`, `{instruction2}.instructions.md`
> **Project config:** `.github/project-config.md` (profile: `{profile}`)
> ═══ PROMPT START — Copy everything between START and END into a new chat ═══
\`\`\`\`
{One-sentence task description}
**Agent context:** You are the `@{agent-name}` agent. Load `.github/project-config.md` before starting.
**Read these files FIRST (in order):**
1. `.github/plans/{plan-file}.md` — **THIS PLAN** — read "Phase N — Step M"
2. {Architecture/PRD doc} — {specific sections}
3. {Target file(s)} — current state
**What to do:**
- {Actionable instruction 1}
- {Actionable instruction 2}
**Acceptance criteria:**
- {Testable criterion 1}
- {Testable criterion 2}
**Scope boundary:**
- Exit gate: Task N.X (the last task in this phase)
- Do NOT proceed to Phase N+1 after the exit gate passes
- Do NOT offer additional work beyond the exit gate tasks
- Commit with: `feat({feature}): Phase N — {description}` and STOP
\`\`\`\`
> ═══ PROMPT END ═══════════════════════════════════════════════════════════
| Task Type | Agent | Agent File |
|---|---|---|
| Models, services, logic | @implement | implement.agent.md |
| Streamlit UI, components | @streamlit-developer | streamlit-developer.agent.md |
| Tests, fixtures | @tester | tester.agent.md |
| SQL queries, schema | @sql-expert | sql-expert.agent.md |
| Docs, README | @docs | docs.agent.md |
| Code review | @code-review | code-review.agent.md |
After saving the plan, offer execution choice:
"Plan complete and saved to .github/plans/<filename>.md. Two execution options:
1. This session — I implement each task sequentially, reviewing between tasks
2. Separate session — Open a new session with the @implement agent and provide the plan path
Which approach?"
If separate session chosen:
@implement agent (.github/agents/implement.agent.md)