@leeovery/claude-technical-workflows 2.0.20 → 2.0.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/skills/technical-discussion/SKILL.md +2 -2
- package/skills/technical-discussion/references/meeting-assistant.md +3 -3
- package/skills/technical-implementation/SKILL.md +3 -3
- package/skills/technical-planning/SKILL.md +3 -3
- package/skills/technical-planning/references/formal-planning.md +1 -1
- package/skills/technical-planning/references/output-backlog-md.md +3 -3
- package/skills/technical-planning/references/output-beads.md +3 -3
- package/skills/technical-planning/references/output-linear.md +3 -3
- package/skills/technical-planning/references/output-local-markdown.md +3 -3
- package/skills/technical-research/SKILL.md +3 -3
- package/skills/technical-review/SKILL.md +2 -2
- package/skills/technical-specification/SKILL.md +9 -8
- package/skills/technical-specification/references/specification-guide.md +45 -22
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: technical-discussion
|
|
3
|
-
description: "Document technical discussions as expert architect and meeting assistant. Capture context, decisions, edge cases, debates, and rationale without jumping to specification or implementation.
|
|
3
|
+
description: "Document technical discussions as expert architect and meeting assistant. Capture context, decisions, edge cases, debates, and rationale without jumping to specification or implementation. Use when: (1) Users discuss/explore/debate architecture or design, (2) Working through edge cases before specification, (3) Need to document technical decisions and their rationale, (4) Capturing competing solutions and why choices were made. Creates documentation in docs/workflow/discussion/{topic}.md that can be used to build validated specifications."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Technical Discussion
|
|
@@ -10,7 +10,7 @@ Act as **expert software architect** participating in discussions AND **document
|
|
|
10
10
|
## Purpose in the Workflow
|
|
11
11
|
|
|
12
12
|
This skill can be used:
|
|
13
|
-
- **Sequentially
|
|
13
|
+
- **Sequentially**: After research or exploration to debate and document decisions
|
|
14
14
|
- **Standalone** (Contract entry): To document technical decisions from any source
|
|
15
15
|
|
|
16
16
|
Either way: Capture decisions, rationale, competing approaches, and edge cases.
|
|
@@ -17,12 +17,12 @@ You're an AI - do both. Engage fully while documenting. Don't dumb down.
|
|
|
17
17
|
|
|
18
18
|
## Workflow
|
|
19
19
|
|
|
20
|
-
**Your role:
|
|
20
|
+
**Your role: discuss and document only**
|
|
21
21
|
|
|
22
22
|
1. **Discuss** - Participate
|
|
23
23
|
2. **Document** - Capture
|
|
24
|
-
3. **Plan** - ❌
|
|
25
|
-
4. **Implement** - ❌
|
|
24
|
+
3. **Plan** - ❌ Not this skill's job
|
|
25
|
+
4. **Implement** - ❌ Not this skill's job
|
|
26
26
|
|
|
27
27
|
Stop after documentation. No plans, implementation steps, or code.
|
|
28
28
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: technical-implementation
|
|
3
|
-
description: "Execute implementation plans using strict TDD workflow with quality gates.
|
|
3
|
+
description: "Execute implementation plans using strict TDD workflow with quality gates. Use when: (1) Implementing a plan from docs/workflow/planning/{topic}.md, (2) User says 'implement', 'build', or 'code this' with a plan available, (3) Ad hoc coding that should follow TDD and quality standards, (4) Bug fixes or features benefiting from structured implementation. Writes tests first, implements to pass, commits frequently, stops for user approval between phases."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Technical Implementation
|
|
@@ -12,7 +12,7 @@ Execute plans through strict TDD. Write tests first, then code to pass them.
|
|
|
12
12
|
## Purpose in the Workflow
|
|
13
13
|
|
|
14
14
|
This skill can be used:
|
|
15
|
-
- **Sequentially
|
|
15
|
+
- **Sequentially**: To execute a plan created by technical-planning
|
|
16
16
|
- **Standalone** (Contract entry): To execute any plan that follows plan-format conventions
|
|
17
17
|
|
|
18
18
|
Either way: Execute via strict TDD - tests first, implementation second.
|
|
@@ -104,7 +104,7 @@ Check the specification when:
|
|
|
104
104
|
|
|
105
105
|
The specification (if available) is the source of truth for design decisions. If no specification exists, the plan is the authority.
|
|
106
106
|
|
|
107
|
-
**Important:** If
|
|
107
|
+
**Important:** If prior source material exists (research notes, discussion documents, etc.), ignore it during implementation. It may contain outdated ideas, rejected approaches, or superseded decisions. The specification filtered and validated that content - refer only to the specification and plan.
|
|
108
108
|
|
|
109
109
|
## Project-Specific Conventions
|
|
110
110
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: technical-planning
|
|
3
|
-
description: "Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria.
|
|
3
|
+
description: "Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Use when: (1) User asks to create/write an implementation plan, (2) User asks to plan implementation from a specification, (3) Converting specifications from docs/workflow/specification/{topic}.md into implementation plans, (4) User says 'plan this' or 'create a plan', (5) Need to structure how to build something with phases and concrete steps. Creates plans in docs/workflow/planning/{topic}.md that can be executed via strict TDD."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Technical Planning
|
|
@@ -12,7 +12,7 @@ Your role spans product (WHAT we're building and WHY) and technical (HOW to stru
|
|
|
12
12
|
## Purpose in the Workflow
|
|
13
13
|
|
|
14
14
|
This skill can be used:
|
|
15
|
-
- **Sequentially
|
|
15
|
+
- **Sequentially**: From a validated specification
|
|
16
16
|
- **Standalone** (Contract entry): From any specification meeting format requirements
|
|
17
17
|
|
|
18
18
|
Either way: Transform specifications into actionable phases, tasks, and acceptance criteria.
|
|
@@ -27,7 +27,7 @@ Either way: Transform specifications into actionable phases, tasks, and acceptan
|
|
|
27
27
|
|
|
28
28
|
## Source Material
|
|
29
29
|
|
|
30
|
-
**The specification is your sole input.** Everything you need should be in the specification - do not request details from
|
|
30
|
+
**The specification is your sole input.** Everything you need should be in the specification - do not request details from prior source material. If information is missing, ask for clarification on the specification itself.
|
|
31
31
|
|
|
32
32
|
## The Process
|
|
33
33
|
|
|
@@ -35,7 +35,7 @@ From the specification (`docs/workflow/specification/{topic}.md`), extract:
|
|
|
35
35
|
- Constraints and requirements
|
|
36
36
|
- **External dependencies** (from the Dependencies section)
|
|
37
37
|
|
|
38
|
-
**The specification is your sole input.**
|
|
38
|
+
**The specification is your sole input.** Prior source materials have already been validated, filtered, and enriched into the specification. Everything you need is in the specification - do not reference other documents.
|
|
39
39
|
|
|
40
40
|
#### Extract External Dependencies
|
|
41
41
|
|
|
@@ -261,9 +261,9 @@ project/
|
|
|
261
261
|
│ ├── task-2 - [P1] Add login endpoint.md
|
|
262
262
|
│ └── task-3 - [P2] Session management.md
|
|
263
263
|
├── docs/workflow/
|
|
264
|
-
│ ├── discussion/{topic}.md #
|
|
265
|
-
│ ├── specification/{topic}.md #
|
|
266
|
-
│ └── planning/{topic}.md #
|
|
264
|
+
│ ├── discussion/{topic}.md # Discussion output
|
|
265
|
+
│ ├── specification/{topic}.md # Specification output
|
|
266
|
+
│ └── planning/{topic}.md # Planning output (format: backlog-md - pointer)
|
|
267
267
|
```
|
|
268
268
|
|
|
269
269
|
## Implementation
|
|
@@ -375,9 +375,9 @@ project/
|
|
|
375
375
|
├── .beads/
|
|
376
376
|
│ └── issues.jsonl # Beads database
|
|
377
377
|
├── docs/workflow/
|
|
378
|
-
│ ├── discussion/{topic}.md #
|
|
379
|
-
│ ├── specification/{topic}.md #
|
|
380
|
-
│ └── planning/{topic}.md #
|
|
378
|
+
│ ├── discussion/{topic}.md # Discussion output
|
|
379
|
+
│ ├── specification/{topic}.md # Specification output
|
|
380
|
+
│ └── planning/{topic}.md # Planning output (format: beads)
|
|
381
381
|
```
|
|
382
382
|
|
|
383
383
|
## Priority Mapping
|
|
@@ -231,9 +231,9 @@ After planning:
|
|
|
231
231
|
|
|
232
232
|
```
|
|
233
233
|
docs/workflow/
|
|
234
|
-
├── discussion/{topic}.md #
|
|
235
|
-
├── specification/{topic}.md #
|
|
236
|
-
└── planning/{topic}.md #
|
|
234
|
+
├── discussion/{topic}.md # Discussion output
|
|
235
|
+
├── specification/{topic}.md # Specification output
|
|
236
|
+
└── planning/{topic}.md # Planning output (format: linear - pointer)
|
|
237
237
|
|
|
238
238
|
Linear:
|
|
239
239
|
└── Project: {topic}
|
|
@@ -234,9 +234,9 @@ After planning:
|
|
|
234
234
|
|
|
235
235
|
```
|
|
236
236
|
docs/workflow/
|
|
237
|
-
├── discussion/{topic}.md #
|
|
238
|
-
├── specification/{topic}.md #
|
|
239
|
-
└── planning/{topic}.md #
|
|
237
|
+
├── discussion/{topic}.md # Discussion output
|
|
238
|
+
├── specification/{topic}.md # Specification output
|
|
239
|
+
└── planning/{topic}.md # Planning output (format: local-markdown)
|
|
240
240
|
```
|
|
241
241
|
|
|
242
242
|
## Implementation
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: technical-research
|
|
3
|
-
description: "Explore ideas, validate concepts, and research broadly across technical, business, and market domains.
|
|
3
|
+
description: "Explore ideas, validate concepts, and research broadly across technical, business, and market domains. Use when: (1) User has a new idea to explore, (2) Need to research a topic deeply, (3) Validating feasibility - technical, business, or market, (4) Learning and exploration without necessarily building anything, (5) User says 'research this' or 'explore this idea', (6) Brain dumping early thoughts before formal discussion. Creates research documents in docs/workflow/research/ that may feed into discussion or specification."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Technical Research
|
|
@@ -10,7 +10,7 @@ Act as **research partner** with broad expertise spanning technical, product, bu
|
|
|
10
10
|
## Purpose in the Workflow
|
|
11
11
|
|
|
12
12
|
This skill can be used:
|
|
13
|
-
- **Sequentially
|
|
13
|
+
- **Sequentially**: First step - explore ideas before detailed discussion
|
|
14
14
|
- **Standalone** (Contract entry): To research and validate any idea, feature, or concept
|
|
15
15
|
|
|
16
16
|
Either way: Explore feasibility (technical, business, market), validate assumptions, document findings.
|
|
@@ -62,7 +62,7 @@ Start with one file. Early research is messy - topics aren't clear, you're follo
|
|
|
62
62
|
|
|
63
63
|
**Let themes emerge**: Over multiple sessions, topics may become distinct. When they do, split into semantic files (`market-landscape.md`, `technical-feasibility.md`).
|
|
64
64
|
|
|
65
|
-
**Periodic review**: Every few sessions, assess: are themes emerging? Split them out. Still fuzzy? Keep exploring. Ready for deeper discussion? Research
|
|
65
|
+
**Periodic review**: Every few sessions, assess: are themes emerging? Split them out. Still fuzzy? Keep exploring. Ready for deeper discussion or specification? Research is complete.
|
|
66
66
|
|
|
67
67
|
## Documentation Loop
|
|
68
68
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: technical-review
|
|
3
|
-
description: "Validate completed implementation against plan tasks and acceptance criteria.
|
|
3
|
+
description: "Validate completed implementation against plan tasks and acceptance criteria. Use when: (1) Implementation is complete, (2) User wants validation before merging/shipping, (3) Quality gate check needed after implementation. Reviews ALL plan tasks for implementation correctness, test adequacy, and code quality. Produces structured feedback (approve, request changes, or comments) - does NOT fix code."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Technical Review
|
|
@@ -20,7 +20,7 @@ Optional but helpful:
|
|
|
20
20
|
## Purpose in the Workflow
|
|
21
21
|
|
|
22
22
|
This skill can be used:
|
|
23
|
-
- **Sequentially
|
|
23
|
+
- **Sequentially**: After implementation of a planned feature
|
|
24
24
|
- **Standalone** (Contract entry): To review any implementation against a plan
|
|
25
25
|
|
|
26
26
|
Either way: Verify every plan task was implemented, tested adequately, and meets quality standards.
|
|
@@ -1,28 +1,29 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: technical-specification
|
|
3
|
-
description: "Build validated specifications from
|
|
3
|
+
description: "Build validated specifications from source material through collaborative refinement. Use when: (1) User asks to create/build a specification from source material, (2) User wants to validate and refine content before planning, (3) Converting source material (discussions, research, requirements) into standalone specifications, (4) User says 'specify this' or 'create a spec', (5) Need to filter hallucinations and enrich gaps before formal planning. Creates specifications in docs/workflow/specification/{topic}.md that can be used to build implementation plans."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Technical Specification
|
|
7
7
|
|
|
8
|
-
Act as **expert technical architect** and **specification builder**. Collaborate with the user to transform
|
|
8
|
+
Act as **expert technical architect** and **specification builder**. Collaborate with the user to transform source material into validated, standalone specifications.
|
|
9
9
|
|
|
10
10
|
Your role is to synthesize reference material, present it for validation, and build a specification that formal planning can execute against.
|
|
11
11
|
|
|
12
12
|
## Purpose in the Workflow
|
|
13
13
|
|
|
14
14
|
This skill can be used:
|
|
15
|
-
- **Sequentially
|
|
16
|
-
- **Standalone
|
|
15
|
+
- **Sequentially**: After source material has been captured (discussions, research, etc.)
|
|
16
|
+
- **Standalone**: With reference material from any source (research docs, conversation transcripts, design documents, inline feature description)
|
|
17
17
|
|
|
18
18
|
Either way: Transform unvalidated reference material into a specification that's **standalone and approved**.
|
|
19
19
|
|
|
20
20
|
### What This Skill Needs
|
|
21
21
|
|
|
22
22
|
- **Source material** (required) - The content to synthesize into a specification. Can be:
|
|
23
|
-
- Discussion
|
|
24
|
-
- Inline feature
|
|
25
|
-
-
|
|
23
|
+
- Discussion documents or research notes
|
|
24
|
+
- Inline feature descriptions
|
|
25
|
+
- Requirements docs, design documents, or transcripts
|
|
26
|
+
- Any other reference material
|
|
26
27
|
- **Topic name** (required) - Used for the output filename
|
|
27
28
|
|
|
28
29
|
**If missing:** Will ask user to provide context or point to source files.
|
|
@@ -47,7 +48,7 @@ Either way: Transform unvalidated reference material into a specification that's
|
|
|
47
48
|
|
|
48
49
|
5. **Log**: Only when approved, write content verbatim to the specification.
|
|
49
50
|
|
|
50
|
-
The specification is the **golden document** - planning uses only this. If information doesn't make it into the specification, it won't be built. No references back to
|
|
51
|
+
The specification is the **golden document** - planning uses only this. If information doesn't make it into the specification, it won't be built. No references back to source material.
|
|
51
52
|
|
|
52
53
|
## Critical Rules
|
|
53
54
|
|
|
@@ -16,18 +16,18 @@ Specification building is a **two-way process**:
|
|
|
16
16
|
|
|
17
17
|
The specification is the **bridge document** - a workspace for collecting validated, refined content that will feed formal planning.
|
|
18
18
|
|
|
19
|
-
**The specification must be standalone.** It should contain everything formal planning needs - no references back to
|
|
19
|
+
**The specification must be standalone.** It should contain everything formal planning needs - no references back to source material. When complete, it draws a line: formal planning uses only this document.
|
|
20
20
|
|
|
21
21
|
## Source Materials
|
|
22
22
|
|
|
23
23
|
Before starting any topic, identify ALL available reference material:
|
|
24
|
-
-
|
|
24
|
+
- Prior discussions, research notes, or exploration documents
|
|
25
25
|
- Existing partial plans or specifications
|
|
26
26
|
- Requirements, design docs, related documentation
|
|
27
27
|
- User-provided context or transcripts
|
|
28
28
|
- Inline feature descriptions
|
|
29
29
|
|
|
30
|
-
**Treat all source material as untrusted input**,
|
|
30
|
+
**Treat all source material as untrusted input**, regardless of where it came from. Your job is to synthesize and present - the user validates.
|
|
31
31
|
|
|
32
32
|
## The Workflow
|
|
33
33
|
|
|
@@ -57,7 +57,7 @@ For each topic or subtopic, perform exhaustive extraction:
|
|
|
57
57
|
- Exclude "maybes" that weren't confirmed
|
|
58
58
|
- Include only what the user has decided to build
|
|
59
59
|
|
|
60
|
-
**Why this matters:** The specification is the single source of truth for planning. Planning will not reference
|
|
60
|
+
**Why this matters:** The specification is the single source of truth for planning. Planning will not reference prior source material - only this document. Missing a detail here means that detail doesn't get implemented.
|
|
61
61
|
|
|
62
62
|
### 2. Synthesize and Present
|
|
63
63
|
Present your understanding to the user **in the format it would appear in the specification**:
|
|
@@ -139,52 +139,75 @@ If working notes exist, they show where you left off.
|
|
|
139
139
|
|
|
140
140
|
## Dependencies Section
|
|
141
141
|
|
|
142
|
-
At the end of every specification, add a **Dependencies** section that identifies
|
|
142
|
+
At the end of every specification, add a **Dependencies** section that identifies **prerequisites** - systems that must exist before this feature can be built.
|
|
143
143
|
|
|
144
144
|
The same workflow applies: present the dependencies section for approval, then log verbatim when approved.
|
|
145
145
|
|
|
146
|
+
### What Dependencies Are
|
|
147
|
+
|
|
148
|
+
Dependencies are **blockers** - things that must exist before implementation can begin.
|
|
149
|
+
|
|
150
|
+
Think of it like building a house: if you're specifying the roof, the walls are a dependency. You cannot build a roof without walls to support it. The walls must exist first.
|
|
151
|
+
|
|
152
|
+
**The test**: "If system X doesn't exist, can we still build this feature?"
|
|
153
|
+
- If **no** → X is a dependency
|
|
154
|
+
- If **yes** → X is not a dependency (even if the systems work together)
|
|
155
|
+
|
|
156
|
+
### What Dependencies Are NOT
|
|
157
|
+
|
|
158
|
+
**Do not list systems just because they:**
|
|
159
|
+
- Work together with this feature
|
|
160
|
+
- Share data or communicate with this feature
|
|
161
|
+
- Are related or in the same domain
|
|
162
|
+
- Would be nice to have alongside this feature
|
|
163
|
+
|
|
164
|
+
Two systems that cooperate are not necessarily dependent. A notification system and a user preferences system might work together (preferences control notification settings), but if you can build the notification system with hardcoded defaults and add preference integration later, then preferences are not a dependency.
|
|
165
|
+
|
|
146
166
|
### How to Identify Dependencies
|
|
147
167
|
|
|
148
|
-
Review the specification for
|
|
149
|
-
|
|
150
|
-
- Data
|
|
151
|
-
-
|
|
152
|
-
-
|
|
168
|
+
Review the specification for cases where implementation is **literally blocked** without another system:
|
|
169
|
+
|
|
170
|
+
- **Data that must exist first** (e.g., "FK to users" → User model must exist, you can't create the FK otherwise)
|
|
171
|
+
- **Events you consume** (e.g., "listens for payment.completed" → Payment system must emit this event)
|
|
172
|
+
- **APIs you call** (e.g., "fetches inventory levels" → Inventory API must exist)
|
|
173
|
+
- **Infrastructure requirements** (e.g., "stores files in S3" → S3 bucket configuration must exist)
|
|
174
|
+
|
|
175
|
+
**Do not include** systems where you merely reference their concepts or where integration could be deferred.
|
|
153
176
|
|
|
154
177
|
### Categorization
|
|
155
178
|
|
|
156
|
-
**Required**:
|
|
179
|
+
**Required**: Implementation cannot start without this. The code literally cannot be written.
|
|
157
180
|
|
|
158
|
-
**Partial Requirement**: Only specific elements are needed, not the full system. Note the minimum scope.
|
|
181
|
+
**Partial Requirement**: Only specific elements are needed, not the full system. Note the minimum scope that unblocks implementation.
|
|
159
182
|
|
|
160
183
|
### Format
|
|
161
184
|
|
|
162
185
|
## Dependencies
|
|
163
186
|
|
|
164
|
-
|
|
187
|
+
Prerequisites that must exist before implementation can begin:
|
|
165
188
|
|
|
166
189
|
### Required
|
|
167
190
|
|
|
168
|
-
| Dependency | Why
|
|
169
|
-
|
|
170
|
-
| **[System Name]** | [
|
|
191
|
+
| Dependency | Why Blocked | What's Unblocked When It Exists |
|
|
192
|
+
|------------|-------------|--------------------------------|
|
|
193
|
+
| **[System Name]** | [Why implementation literally cannot proceed] | [What parts of this spec can then be built] |
|
|
171
194
|
|
|
172
195
|
### Partial Requirement
|
|
173
196
|
|
|
174
|
-
| Dependency | Why
|
|
175
|
-
|
|
176
|
-
| **[System Name]** | [
|
|
197
|
+
| Dependency | Why Blocked | Minimum Scope Needed |
|
|
198
|
+
|------------|-------------|---------------------|
|
|
199
|
+
| **[System Name]** | [Why implementation cannot proceed] | [Specific subset that unblocks us] |
|
|
177
200
|
|
|
178
201
|
### Notes
|
|
179
202
|
|
|
180
|
-
- [
|
|
181
|
-
- [Workarounds
|
|
203
|
+
- [What can be built independently, without waiting]
|
|
204
|
+
- [Workarounds if dependencies don't exist yet]
|
|
182
205
|
|
|
183
206
|
### Purpose
|
|
184
207
|
|
|
185
208
|
This section feeds into the planning phase, where dependencies become blocking relationships between epics/phases. It helps sequence implementation correctly.
|
|
186
209
|
|
|
187
|
-
|
|
210
|
+
**Key distinction**: This is about sequencing what must come first, not mapping out what works together. A feature may integrate with many systems - only list the ones that block you from starting.
|
|
188
211
|
|
|
189
212
|
## Completion
|
|
190
213
|
|