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 (G-001 format)
/kramme:siw:generate-phases         # Break spec into phase-based issues (P1-001, P2-001)
/kramme:siw:implement-issue G-001   # Start implementing
/kramme:siw:restart-issues          # Remove DONE issues, renumber within groups
/kramme:siw:reset                   # Reset for next iteration (keeps spec)
/kramme:siw:remove                  # Clean up when done

Issue Naming

Issues use prefix-based numbering:

• •G-XXX — General issues (standalone, non-phase)
• •P1-XXX, P2-XXX, etc. — Phase-specific issues

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 general work items (G-XXX)
│  /kramme:siw:generate-phases     │  Create phase-based issues (P1-XXX, P2-XXX)
│  → siw/issues/ISSUE-{prefix}-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-G-001-setup.md        # General issues
│   │   ├── ISSUE-G-002-docs.md
│   │   ├── ISSUE-P1-001-feature-a.md   # Phase 1 issues
│   │   ├── ISSUE-P1-002-feature-b.md
│   │   └── ISSUE-P2-001-bug-fix.md     # Phase 2 issues
│   └── 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