majiayu000 Structured Implementation Workflow
When to Use
- Complex features requiring planning and decision tracking
- Comprehensive documentation or detailed technical content
- Multi-day projects with investigation and research phases
- Technical designs, API documentation, or system architecture
NOT for: Small bug fixes (<1 day), trivial updates, simple refactoring, quick documentation fixes.
Three-Document System
| Document | Purpose | Persistence |
|---|---|---|
| [YOUR_SPEC].md | Main specification (single source of truth) | PERMANENT |
| OPEN_ISSUES_OVERVIEW.md + issues/*.md | Active blockers and investigations | Temporary |
| LOG.md | Session progress + decision rationale | Temporary |
Document name: Choose spec name in Phase 1 (FEATURE_SPECIFICATION.md, API_DESIGN.md, PROJECT_PLAN.md, etc.)
Issues: Overview table + individual issue files for progressive disclosure.
Critical Rules
- [YOUR_SPEC].md NEVER references OPEN_ISSUES.md or LOG.md (it's self-contained and permanent)
- NEVER reference temp docs in deliverables (code comments, docs, error messages, logs)
- Information flows one-way: Issues → LOG (progress + decisions) → [YOUR_SPEC].md
- After completing tasks: ALWAYS ask user to review unless they've opted out
Document Flow
┌──────────────────────────────────┐
│ OPEN_ISSUES_OVERVIEW.md │ ⏳ Temporary
│ + issues/ISSUE-XXX-*.md │ Track blockers (overview + details)
└──────────────┬───────────────────┘
│ Investigation & resolution
↓
┌──────────────────────────────────┐
│ LOG.md │ ⏳ Temporary - progress + WHY
└──────────────┬───────────────────┘
│ Final details incorporated
↓
┌──────────────────────────────────┐
│ [YOUR_SPEC].md │ ⚠️ PERMANENT - single source of truth
└──────────────────────────────────┘
Getting Started
First, check for existing workflow files:
ls LOG.md OPEN_ISSUES_OVERVIEW.md *SPEC*.md *SPECIFICATION*.md 2>/dev/null
Entry Point Decision
| State | Action |
|---|---|
| No files exist | Starting fresh → Read resources/phase-1-planning.md |
| LOG.md exists | Resuming work → Read resources/phase-0-resuming.md |
| Blocked/need decision | Investigation → Read resources/phase-2-investigation.md |
| Executing tasks | Execution → Read resources/phase-3-execution.md |
| All tasks complete | Completion → Read resources/phase-4-completion.md |
When Creating Documents
| Document | Template to Read |
|---|---|
| [YOUR_SPEC].md | resources/templates/spec-guidance.md |
| LOG.md | resources/templates/log-template.md |
| Issues (overview + files) | resources/templates/issues-template.md |
Resource Reference
All resources are in this skill's directory: skills/kramme:structured-implementation-workflow/resources/
Phase Resources:
phase-0-resuming.md- Entry point for existing projectsphase-1-planning.md- Creating documents from scratchphase-2-investigation.md- Handling blockers and decisionsphase-3-execution.md- Working through tasksphase-4-completion.md- Review and completion checklist
Templates:
templates/spec-guidance.md- [YOUR_SPEC].md guidancetemplates/log-template.md- LOG.md structure and examplestemplates/issues-template.md- Issues structure (overview + individual files)
Guideline Keywords
- ALWAYS/NEVER — Mandatory (exceptions require explicit approval)
- PREFER — Strong recommendation (exceptions allowed)
- CAN — Optional, developer's discretion
- NOTE — Context or clarification
File Locations
Place all workflow files in your project/work directory root:
/
├── [YOUR_SPEC].md ⚠️ PERMANENT (name based on project type)
├── OPEN_ISSUES_OVERVIEW.md ⏳ Temporary (deleted after completion)
├── issues/ ⏳ Temporary directory
│ ├── ISSUE-001-*.md
│ └── ISSUE-002-*.md
├── LOG.md ⏳ Temporary (deleted after completion)
├── AGENTS.md (optional - project-wide guidelines)
└── CLAUDE.md (optional - AI-specific instructions)
Integration: If your project has AGENTS.md, check it for implementation best practices.