kramme:structured-implementation-workflow

Structured Implementation Workflow (SIW)

A local issue tracking system using markdown files to plan, track, and document implementations without requiring external services.

When to Use

• Complex features requiring planning and decision tracking
• Multi-issue projects with multiple work items
• Projects without Linear or when you want local-only tracking
• Technical designs, API documentation, or system architecture

NOT for: Small bug fixes (<1 day), trivial updates, simple refactoring.

Quick Start

/​kramme:siw:init                    # Initialize workflow documents
/​kramme:siw:define-issue "feature"  # Create a work item
/​kramme:siw:implement-issue 001     # Start implementing
/​kramme:siw:restart-issues          # Remove DONE issues, renumber from 001
/​kramme:siw:reset                   # Reset for next iteration (keeps spec)
/​kramme:siw:remove                  # Clean up when done

Three-Document System

What Each Document Contains

Specification (PERMANENT):

• Project overview and objectives
• Scope (in/​out)
• Design decisions (migrated from siw/​LOG.md)
• Success criteria

Supporting Specs (PERMANENT, optional):

• Detailed specifications organized by domain
• Examples: data model, API design, UI specs, user stories
• Named with ordering prefix: 00-overview.md, 01-data-model.md, etc.
• Main spec references these via TOC

Issues (TEMPORARY):

• Individual work items (features, bugs, improvements)
• Each issue has: problem, context, scope, acceptance criteria
• Deleted when implemented

siw/​LOG.md (TEMPORARY):

• Current progress and status
• Decision log with rationale
• Session continuity between conversations

Document Flow

┌──────────────────────────────────┐
│  /​kramme:siw:define-issue        │  Create work items
│  → siw/​issues/​ISSUE-XXX-*.md     │
└──────────────┬───────────────────┘
               │ Implementation
               ↓
┌──────────────────────────────────┐
│  /​kramme:siw:implement-issue     │  Work on issues
│  → siw/​LOG.md (progress + decisions) │
└──────────────┬───────────────────┘
               │ Decisions migrated
               ↓
┌──────────────────────────────────┐
│  siw/[YOUR_SPEC].md              │  ⚠️ PERMANENT - single source of truth
│  (updated via sync step)         │
└──────────────────────────────────┘

Critical Rules

1. Spec NEVER references temp docs - It's self-contained and permanent
2. NEVER reference temp docs in code - Comments, docs, error messages must not mention siw/​LOG.md or siw/​issues
3. Decisions flow one-way: Issues → siw/​LOG.md → siw/[YOUR_SPEC].md
4. Sync before completion: Always run Step 10 (Spec Sync) in implement-issue

---

Commands Reference

---

Working With Existing Files

When SIW files already exist, check the current state:

ls siw/​LOG.md siw/​OPEN_ISSUES_OVERVIEW.md siw/​*SPEC*.md siw/​*SPECIFICATION*.md siw/​issues/ 2>/​dev/​null

Entry Point Decision

Resuming Work

When resuming a session with existing SIW files:

1. Read siw/​LOG.md first - Check "Current Progress" section for:

   • What was last completed
   • What's next
   • Any blockers

2. Check siw/​OPEN_ISSUES_OVERVIEW.md - See which issues are:

   • READY (not started)
   • IN PROGRESS (being worked on)
   • IN REVIEW (awaiting review/​approval)
   • DONE (completed)

3. Continue or start new - Either:

   • Continue the in-progress issue
   • Pick up the next ready issue with /​kramme:siw:implement-issue

---

Issue Lifecycle

Created              In Progress           Review              Completed
   │                      │                   │                    │
   ▼                      ▼                   ▼                    ▼
┌─────────┐          ┌─────────┐        ┌─────────┐          ┌─────────┐
│  READY  │ ───────► │IN PROG  │ ─────► │IN REVIEW│ ───────► │  DONE   │
└─────────┘          └─────────┘        └─────────┘          └─────────┘

Issue States:

• READY - Defined, waiting to be picked up
• IN PROGRESS - Currently being implemented
• IN REVIEW - Work complete, awaiting review/​approval
• DONE - Finalized (issue file deleted or marked complete)

When an issue is completed:

1. Decisions are logged in siw/​LOG.md
2. Key decisions are synced to spec (Step 10)
3. Issue file is deleted
4. Row removed from siw/​OPEN_ISSUES_OVERVIEW.md

---

File Locations

All workflow files live in the siw/ folder in the project root:

/
├── siw/
│   ├── [YOUR_SPEC].md              ⚠️ PERMANENT (name chosen at init)
│   ├── supporting-specs/           ⚠️ PERMANENT (optional, for large projects)
│   │   ├── 00-overview.md
│   │   ├── 01-data-model.md
│   │   ├── 02-api-specification.md
│   │   └── 03-ui-specification.md
│   ├── OPEN_ISSUES_OVERVIEW.md     ⏳ Temporary
│   ├── issues/                     ⏳ Temporary directory
│   │   ├── ISSUE-001-feature-a.md
│   │   └── ISSUE-002-bug-fix.md
│   └── LOG.md                      ⏳ Temporary
├── AGENTS.md                       (optional)
└── CLAUDE.md                       (optional)

When to Use Supporting Specs

Use siw/​supporting-specs/ when:

• Main spec exceeds ~500 lines
• Multiple distinct domains (data model, API, UI, user stories)
• Different team members own different sections
• You want targeted reading during execution

Naming convention: NN-descriptor.md (e.g., 01-data-model.md, 02a-cms-ui.md)

---

Templates Reference

When manually creating documents, use these templates from: skills/​kramme:structured-implementation-workflow/​resources/​templates/

Tip: Using /​kramme:siw:init and /​kramme:siw:define-issue is preferred over manual creation.

---

Phase Resources

For detailed guidance on specific phases, read:

---

Guideline Keywords

• ALWAYS/​NEVER — Mandatory (exceptions require explicit approval)
• PREFER — Strong recommendation (exceptions allowed)
• CAN — Optional, developer's discretion
• NOTE — Context or clarification