workflow-reference

Name: workflow-reference
Author: neuromechanist

37stars7forks

How to install workflow-reference?

neuromechanist/research-skills/workflow-reference

$npx -y skills add neuromechanist/research-skills --skill workflow-reference

Installs into the current project.

Summary

This skill should be used when executing the epic-dev workflow, creating epic branches, managing sprint phases, working with git worktrees for phased feature development, or when the user mentions "epic dev", "epic-dev", "/epic-dev", "epic workflow", "sprint phases", "phased deve

Files · 1

View on GitHub

SKILL.md

1	# Epic/Sprint Development Workflow Reference
2
3	Procedural reference for multi-phase feature development using git worktrees, GitHub issues with sub-issues, and phased PR delivery.
4
5	## Phase Sizing and Epic-vs-Single Decision
6
7	One phase = one independently reviewable and testable PR: roughly one
8	subsystem, one migration, or up to ~500 net lines of non-generated change.
9
10	- The description contains 2+ such units -> epic (this workflow).
11	- Exactly one unit -> single-phase shortcut (below), or simply the
12	engineering-loop skill without epic machinery.
13	- Unsure how to break a description into phases: each phase must have its own
14	testable Definition of Done; if two candidate phases can only be tested
15	together, they are one phase.
16
17	Slug derivation for names: take the phase title, drop stopwords, keep 2-3
18	words with the object noun first, kebab-case ("backend-metrics",
19	"sync-engine"; never "implement-the-new-backend-metrics").
20
21	Related skills: implementation-planning (writing each phase plan),
22	agent-fanout (parallel implementers, one worktree each), engineering-loop
23	(the inner loop within a phase), debugging (when a phase's tests fail for
24	unclear reasons).
25
26	## Model handoff by phase
27
28	The lead model owns epic decomposition, architecture, observation,
29	approval-gate decisions, verification, and synthesis. In Codex use Sol; in
30	Claude use Fable when available, otherwise Opus. Once architecture is approved,
31	an intermediate planner may produce the detailed phase brief (Codex Terra;
32	Claude Sonnet only when no design judgment remains). A named worker implements
33	that brief in the isolated worktree (Codex Luna or Claude Sonnet). Fresh worker
34	reviewers validate each phase, while high-risk or architectural findings return
35	to the lead. Close/remove one-off agents after their reports are incorporated.
36
37	## Branch Strategy Decision Tree
38
39	Determine the integration branch and branching model:
40
41	1. Integration branch detection:
42	- If `develop` branch exists (local or remote): integration branch = `develop`
43	- Otherwise: integration branch = default branch (`main` or `master`)
44
45	2. Epic branch:
46	- Named: `feature/issue-{N}-epic-{short-name}`
47	- Created from: integration branch
48	- Purpose: collects all phase PRs before final merge to integration
49
50	3. Phase branches:
51	- Named: `feature/issue-{N}-phase{X}-{short-name}`
52	- Created from: epic branch
53	- Merged to: epic branch (squash merge)
54
55	4. Single-phase shortcut:
56	- If only one phase, skip the epic branch layer
57	- Create feature branch directly from integration branch
58	- Merge directly to integration branch
59
60	## State File Format
61
62	Persistent state stored in `.claude/epic.local.md` (gitignored via `.claude/*.local.md`):
63
64	```yaml
65	---
66	epic_issue: 132
67	epic_title: "Feature: Community Dashboard"
68	integration_branch: develop
69	epic_branch: feature/issue-132-epic-dashboard
70	worktree_base: "../epic-dashboard"
71	phases:
72	- number: 1
73	title: "Backend metrics collection"
74	issue: 133
75	branch: "feature/issue-133-phase1-metrics"
76	status: complete # pending \| in_progress \| complete
77	pr: 135
78	- number: 2
79	title: "Dashboard frontend"
80	issue: 134
81	branch: "feature/issue-134-phase2-frontend"
82	status: pending
83	pr: null
84	current_phase: 2
85	created_at: "2026-02-02T12:00:00Z"
86	---
87
88	## Notes
89	Running notes about the epic, decisions made, blockers encountered.
90	```
91
92	Status transitions: `pending` -> `in_progress` -> `complete`
93
94	## Git Worktree Operations
95
96	All worktree paths use absolute paths (Bash calls do not persist `cd`).
97
98	Create epic worktree:
99	```bash
100	REPO_ROOT=$(git rev-parse --show-toplevel)
101	PARENT=$(dirname "$REPO_ROOT")
102	git worktree add "$PARENT/epic-{short-name}" -b feature/issue-{N}-epic-{short-name} {integration_branch}
103	```
104
105	Create phase worktree from epic branch:
106	```bash
107	git worktree add "$PARENT/{short-name}-phase{X}" -b feature/issue-{N}-phase{X}-{short-name} feature/issue-{EPIC}-epic-{epic-name}
108	```
109
110	Clean up worktree after merge:
111	```bash
112	git worktree remove "$PARENT/{worktree-name}"
113	git branch -d feature/issue-{N}-phase{X}-{short-name}
114	```
115
116	Handle existing worktree: Before creating, check:
117	```bash
118	git worktree list \| grep -q "{branch-name}" && echo "EXISTS" \|\| echo "NEW"
119	```
120
121	## GitHub Operations
122
123	Semantic line breaks remain the default for prose source. GitHub issue and
124	pull-request bodies are the exception: keep each paragraph on one source line,
125	separate paragraphs with blank lines, and do not insert sentence- or
126	clause-level newlines inside a paragraph.
127
128	Create epic issue:
129	```bash
130	gh issue create --title "Epic: {description}" --label "feat

People who liked this also viewed

6 picks

Type

workflow-reference

37stars7forks

View on GitHub

How to install workflow-reference?

neuromechanist/research-skills/workflow-reference

$npx -y skills add neuromechanist/research-skills --skill workflow-reference

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Epic/Sprint Development Workflow Reference
2
3	Procedural reference for multi-phase feature development using git worktrees, GitHub issues with sub-issues, and phased PR delivery.
4
5	## Phase Sizing and Epic-vs-Single Decision
6
7	One phase = one independently reviewable and testable PR: roughly one
8	subsystem, one migration, or up to ~500 net lines of non-generated change.
9
10	- The description contains 2+ such units -> epic (this workflow).
11	- Exactly one unit -> single-phase shortcut (below), or simply the
12	engineering-loop skill without epic machinery.
13	- Unsure how to break a description into phases: each phase must have its own
14	testable Definition of Done; if two candidate phases can only be tested
15	together, they are one phase.
16
17	Slug derivation for names: take the phase title, drop stopwords, keep 2-3
18	words with the object noun first, kebab-case ("backend-metrics",
19	"sync-engine"; never "implement-the-new-backend-metrics").
20
21	Related skills: implementation-planning (writing each phase plan),
22	agent-fanout (parallel implementers, one worktree each), engineering-loop
23	(the inner loop within a phase), debugging (when a phase's tests fail for
24	unclear reasons).
25
26	## Model handoff by phase
27
28	The lead model owns epic decomposition, architecture, observation,
29	approval-gate decisions, verification, and synthesis. In Codex use Sol; in
30	Claude use Fable when available, otherwise Opus. Once architecture is approved,
31	an intermediate planner may produce the detailed phase brief (Codex Terra;
32	Claude Sonnet only when no design judgment remains). A named worker implements
33	that brief in the isolated worktree (Codex Luna or Claude Sonnet). Fresh worker
34	reviewers validate each phase, while high-risk or architectural findings return
35	to the lead. Close/remove one-off agents after their reports are incorporated.
36
37	## Branch Strategy Decision Tree
38
39	Determine the integration branch and branching model:
40
41	1. Integration branch detection:
42	- If `develop` branch exists (local or remote): integration branch = `develop`
43	- Otherwise: integration branch = default branch (`main` or `master`)
44
45	2. Epic branch:
46	- Named: `feature/issue-{N}-epic-{short-name}`
47	- Created from: integration branch
48	- Purpose: collects all phase PRs before final merge to integration
49
50	3. Phase branches:
51	- Named: `feature/issue-{N}-phase{X}-{short-name}`
52	- Created from: epic branch
53	- Merged to: epic branch (squash merge)
54
55	4. Single-phase shortcut:
56	- If only one phase, skip the epic branch layer
57	- Create feature branch directly from integration branch
58	- Merge directly to integration branch
59
60	## State File Format
61
62	Persistent state stored in `.claude/epic.local.md` (gitignored via `.claude/*.local.md`):
63
64	```yaml
65	---
66	epic_issue: 132
67	epic_title: "Feature: Community Dashboard"
68	integration_branch: develop
69	epic_branch: feature/issue-132-epic-dashboard
70	worktree_base: "../epic-dashboard"
71	phases:
72	- number: 1
73	title: "Backend metrics collection"
74	issue: 133
75	branch: "feature/issue-133-phase1-metrics"
76	status: complete # pending \| in_progress \| complete
77	pr: 135
78	- number: 2
79	title: "Dashboard frontend"
80	issue: 134
81	branch: "feature/issue-134-phase2-frontend"
82	status: pending
83	pr: null
84	current_phase: 2
85	created_at: "2026-02-02T12:00:00Z"
86	---
87
88	## Notes
89	Running notes about the epic, decisions made, blockers encountered.
90	```
91
92	Status transitions: `pending` -> `in_progress` -> `complete`
93
94	## Git Worktree Operations
95
96	All worktree paths use absolute paths (Bash calls do not persist `cd`).
97
98	Create epic worktree:
99	```bash
100	REPO_ROOT=$(git rev-parse --show-toplevel)
101	PARENT=$(dirname "$REPO_ROOT")
102	git worktree add "$PARENT/epic-{short-name}" -b feature/issue-{N}-epic-{short-name} {integration_branch}
103	```
104
105	Create phase worktree from epic branch:
106	```bash
107	git worktree add "$PARENT/{short-name}-phase{X}" -b feature/issue-{N}-phase{X}-{short-name} feature/issue-{EPIC}-epic-{epic-name}
108	```
109
110	Clean up worktree after merge:
111	```bash
112	git worktree remove "$PARENT/{worktree-name}"
113	git branch -d feature/issue-{N}-phase{X}-{short-name}
114	```
115
116	Handle existing worktree: Before creating, check:
117	```bash
118	git worktree list \| grep -q "{branch-name}" && echo "EXISTS" \|\| echo "NEW"
119	```
120
121	## GitHub Operations
122
123	Semantic line breaks remain the default for prose source. GitHub issue and
124	pull-request bodies are the exception: keep each paragraph on one source line,
125	separate paragraphs with blank lines, and do not insert sentence- or
126	clause-level newlines inside a paragraph.
127
128	Create epic issue:
129	```bash
130	gh issue create --title "Epic: {description}" --label "feat

People who liked this also viewed

6 picks

Type