dev-workflow

Development Workflow

When This Skill MUST Be Used

ALWAYS invoke this skill when the user's request involves ANY of these:

• Starting any structured development session (concept, phase, objective, task, review, or release)
• Creating or developing a new concept
• Phase planning (breaking a phase into objectives) or objective planning (breaking an objective into sub-issues)
• Executing a development task from a GitHub issue
• Reviewing project infrastructure and codebase health
• Tagging a release
• Session closeout activities
• Creating or archiving context documents

Session Metadata

Before starting a session, collect the required metadata based on session type.

Invocation patterns:

Pattern	Session Type	Example
/dev-workflow concept	Concept Development	/dev-workflow concept
/dev-workflow phase	Phase Planning	/dev-workflow phase
/dev-workflow objective <issue>	Objective Planning	/dev-workflow objective 5
/dev-workflow task <issue-number>	Task Execution	/dev-workflow task 42
/dev-workflow review	Project Review	/dev-workflow review
/dev-workflow release <version>	Release	/dev-workflow release v0.2.0

Concept Development

1. Concept name - descriptive slug (e.g., audio-protocol). Derived from argument or collected from user.
2. Scope - extend existing repository or initialize new project.
3. Target repositories - which repos are affected by the concept.

Phase Planning

1. Phase name - identified from the Phases roadmap in _project/README.md or collected from the user.
2. Version target - the semantic version this phase builds toward (from the Phases roadmap).
3. Primary repository - where Objectives will be created.
4. _project/README.md - read from the primary repository for vision, architecture, and the Phases roadmap.

Objective Planning

1. Issue number - required, from argument. The Objective (parent issue) to plan.
2. Target repositories - identified from the Objective body or collected from the user.

Task Execution

1. Issue number - required, from argument. Read the issue to bootstrap session context.

Project Review

1. Scope - repository name or project name being reviewed. Defaults to current repository.

Release

1. Version - required, from argument (e.g., /dev-workflow release v0.2.0). Must follow semantic versioning.

Session Types

Concept Development Session

Develops a new idea from initial requirements to a project concept with long-term vision. Defines Phases as areas of focus, initializes repository and project board infrastructure, and produces a concept document (_project/README.md for new projects). Does NOT create Objectives or sub-issues — those are created during phase and objective planning sessions.

Skills loaded: project-management:project-management, github-cli:github-cli

See concept.md for the full workflow.

Phase Planning Session

Takes a Phase (produced by concept development) and decomposes it into Objectives (parent issues with the objective label and Objective issue type). This is the primary entry point for creating Objectives, which are created on the primary repository and documented in _project/phase.md. When a previous phase exists, the session begins with a transition closeout that handles incomplete work (transitioning objectives to the new phase or moving them to backlog) before clearing the slate.

Skills loaded: project-management:project-management, github-cli:github-cli

See phase.md for the full workflow.

Objective Planning Session

Takes an Objective and produces sub-issues across the relevant repositories, each assigned the Task (or Bug) issue type. This is where architecture details are ironed out and the scope of each development session is defined. Each sub-issue maps to exactly one branch and one PR, and is documented in _project/objective.md. When a previous objective exists, the session begins with a transition closeout that handles incomplete sub-issues (carrying them forward to the new objective or moving them to backlog) before clearing the slate.

Skills loaded: project-management:project-management, github-cli:github-cli

See objective.md for the full workflow.

Task Execution Session

Issue-driven development session starting in Claude Code plan mode. Creates a branch, collaboratively plans the implementation, generates an implementation guide, and performs structured closeout including PR creation and project-management updates.

Skills loaded: github-cli:github-cli

See task.md for the full workflow.

Project Review Session

Evaluates the alignment between project-management infrastructure and the current state of the codebase. Ensures the long-term vision is on track and produces a review report.

Skills loaded: project-management:project-management, github-cli:github-cli

See review.md for the full workflow.

Release Session

Two release types: dev releases (per-PR pre-release tags like v0.1.0-dev.3.7) and phase releases (final version like v0.1.0). Dev releases are triggered after a PR is merged — the CHANGELOG entry is created during task execution closeout (Phase 8c), and the release session handles tagging and verification. Phase releases finalize a version by consolidating dev tag CHANGELOG sections, running validation, and tagging.

Skills loaded: github-cli:github-cli

See release.md for the full workflow.

Context Document Convention

Context documents are persistent project knowledge artifacts stored in .claude/context/. They are distinct from plan files (.claude/plans/), which are ephemeral session working memory.

Directory Structure

.claude/context/
├── concepts/                         # Concept development outputs
│   └── .archive/                     # Superseded or completed concepts
├── guides/                           # Active implementation guides
│   └── .archive/                     # Archived after session closeout
├── sessions/                         # Session summaries
│   └── .archive/                     # Historical summaries
└── reviews/                          # Project review reports
    └── .archive/                     # Historical reviews

Directories are created on demand when the first artifact is placed in them.

Naming Conventions

Type	Pattern	Example
Concept	[slug].md	audio-protocol.md
Implementation guide	[issue-number]-[slug].md	42-audio-protocol.md
Session summary	[issue-number]-[slug].md	42-audio-protocol.md
Review report	[YYYY-MM-DD]-[scope].md	2026-02-03-kernel.md

Lifecycle

State	Location	Trigger
Active concept	context/concepts/[slug].md	Created during concept development
Archived concept	context/concepts/.archive/[slug].md	Concept fully implemented or superseded
Active guide	context/guides/[issue-number]-[slug].md	Created during task execution
Archived guide	context/guides/.archive/[issue-number]-[slug].md	Moved during session closeout
Session summary	context/sessions/[issue-number]-[slug].md	Created during session closeout
Archived summary	context/sessions/.archive/[issue-number]-[slug].md	Moved during project review when no longer referenced
Active review	context/reviews/[YYYY-MM-DD]-[scope].md	Created during project review
Archived review	context/reviews/.archive/[YYYY-MM-DD]-[scope].md	Superseded by a newer review

Relationship to Plan Files

Aspect	Plan Files (.claude/plans/)	Context Documents (.claude/context/)
Purpose	Session-scoped working memory	Persistent project knowledge
Created by	Claude Code plan mode	Session workflows
Lifecycle	Disposable after session	Versioned, archived, never deleted
Naming	Auto-generated slugs	Structured conventions

A task execution session starts in plan mode (producing a plan file), then transforms the plan into an implementation guide in .claude/context/guides/. The plan file can be cleaned up at the developer's discretion.

Skill Integration

Session Type	Skills Loaded
Concept Development	project-management:project-management, github-cli:github-cli
Phase Planning	project-management:project-management, github-cli:github-cli
Objective Planning	project-management:project-management, github-cli:github-cli
Task Execution	github-cli:github-cli
Project Review	project-management:project-management, github-cli:github-cli
Release	github-cli:github-cli

Scope boundary: This skill orchestrates session workflows. It delegates specific operations to the appropriate skill (project-management:project-management for infrastructure, github-cli:github-cli for issue/PR operations).