Workflow Documentation

Decisions

• Pending: Should this be one document or split into sections (e.g., workflow-sessions.md, workflow-features.md)?
• Pending: Should there be a /workflow skill that shows a quick summary?
• Pending: Include a visual flowchart (Mermaid diagram) for the feature lifecycle?

User Tasks

---

FR-030: Workflow Documentation

Summary

A living workflow document that describes how to work with Opus — from session start to finish — with periodic reviews to keep it accurate.

Problem / Motivation

The system is growing: skills, hooks, agents, rules, conventions, feature lifecycle, protected files, anti-hallucination rules, etc. This knowledge is scattered across CLAUDE.md, vault conventions, skill definitions, and the user’s head. There’s no single document that answers: “How do I actually work with this system day-to-day?”

Without a clear workflow document:

• New sessions start without context on the intended workflow
• The user can’t quickly reference how things should work
• As the system evolves, old workflows become stale without anyone noticing

Proposed Solution

Create a workflow document in vault/00_system/docs/workflow.md that describes the complete working process, and set up periodic reviews to keep it current.

What the workflow document covers

1. Session workflow — What happens at session start/end, how to pick up where you left off
2. Feature workflow — How to create, plan, build, and complete features (the full lifecycle)
3. Daily operations — Briefings, changelogs, thoughts capture
4. Skill reference — When and how to use each skill (/briefing, /learn, /idea, etc.)
5. Conventions — File naming, vault structure, commit messages, protected files
6. Self-improvement workflow — How proposals work, when to create them, review cycle
7. Quick reference — Common commands and paths cheat sheet

Periodic review mechanism

• The workflow document includes a last-reviewed date in its frontmatter
• FR-049 (System Self-Review) should include workflow.md in its review checklist
• When skills, hooks, or conventions change, the changelog should flag “workflow may need update”
• Suggested review cadence: every 2 weeks or after any major system change

---

Open Questions

• Should this be one document or split into sections (e.g., workflow-sessions.md, workflow-features.md)?
• Should there be a /workflow skill that shows a quick summary?
• Include a visual flowchart (Mermaid diagram) for the feature lifecycle?

---

Phase Overview

Phase	Description	Status
Phase 1	Create initial workflow document	—
Phase 2	Review mechanism + automation	—

---

Phase 1: Initial Workflow Document —

Goal: Draft and finalize a comprehensive workflow document based on current system state.

File / Feature	Details	Owner	Status
Draft workflow.md	Write vault/00_system/docs/workflow.md based on current system state	opus	—
Session workflow	Document session start/end behavior	opus	—
Feature lifecycle	Document the full feature lifecycle with examples	opus	—
Skill reference	Document all available skills and when to use them	opus	—
Conventions summary	Consolidate all naming/structure conventions	opus	—
User review	Get user approval before finalizing (protected path)	mv	—

---

Phase 2: Review Mechanism —

Goal: Set up periodic reviews and automation to keep the workflow document current.

File / Feature	Details	Owner	Status
Add last-reviewed frontmatter	Track when workflow was last reviewed	mv	—
Link to FR-049	Include workflow.md in system self-review checklist	mv	—
Changelog flag	When system changes happen, flag workflow for review	mv	—
/workflow skill	Optional quick-reference skill	opus	—

Acceptance Criteria:

• vault/00_system/docs/workflow.md exists and covers all major workflows
• Document is readable and useful as a standalone reference
• last-reviewed date is tracked
• FR-049 review checklist includes workflow.md
• Document is updated after any major system change

Notes:

• This is a protected file path (vault/00_system/**), so always ask for user confirmation before changes
• Should reflect reality, not aspirations — only document what actually works today
• Keep it concise — this is a reference, not a tutorial

---

Prerequisites / Gap Analysis

Requirements

Requirement	Description
REQ-1	Current system state must be well-defined enough to document

Current State

Component	Status	Details
CLAUDE.md	done	Core instructions exist
Skills	WIP	Several skills defined
Hooks	—	Not yet implemented
Workflow document	—	Does not exist

Gap (What’s missing?)

Gap	Effort	Blocker?
Workflow document	Med	No
Review mechanism	Low	No

---

Test

Manual tests

Test	Expected	Actual	Last
workflow.md exists	File at vault/00_system/docs/workflow.md	pending	-
Covers all major workflows	Session, feature, daily, skills, conventions	pending	-
last-reviewed date tracked	Frontmatter field present	pending	-

AI-verified tests

Scenario	Expected behavior	Verification method
…	…	…

E2E tests

Scenario	Assertion
…	…

Integration tests

Component	Coverage
…	…

Unit tests

Component	Tests	Coverage
…	…	…

---

History

Date	Event	Details
2026-02-26	Created
2026-02-27	Renumbered	From FR-011 to FR-030
2026-02-28	Reformatted	Aligned to feature-request template

---

References

• FR-049 (System Self-Review) — periodic review mechanism
• FR-028 (Feature Workflow Automation) — feature lifecycle it documents