chore: bootstrap skills library — 19 skills + installer + CI auto-tag
Some checks failed
release / tag (push) Has been cancelled
Some checks failed
release / tag (push) Has been cancelled
Phase 1 of mathias/skills extraction (infra#62 Track D — homelab next-step plan addendum). Imports ~/dev/.skills/ verbatim (19 skill dirs + SKILLS_INDEX.md) and adds the installation surface: - Taskfile.yml — install / update / list / release / check targets - install.sh — bootstrap installer for hosts without Task. Idempotent symlink wirer; default checkout at ~/.local/share/skills/ on every host; SKILLS_REF env var pins a tag (default: main). - .gitea/workflows/release.yml — auto-tag every push to main by Bump-Type footer (major/minor/patch, default patch). Skipped when commit contains [skip-release]. - README — usage, versioning, contribution flow, secret-hygiene rule. Phase 1 wires Claude Code only (~/.claude/skills/<name> global + <repo>/.claude/skills/<name> per-repo). Phase 2 adds Crush, opencode, antigravity, and gitea-resident agents (cobalt-dingo, agentsquad) once their skill conventions are researched. Public repo, markdown-only — no secrets, no client names. Verified via pre-push grep before initial push. [skip-release]
This commit is contained in:
Mathias
276
planning/SKILL.md
Normal file
276
planning/SKILL.md
Normal file
@@ -0,0 +1,276 @@
|
||||
---
|
||||
name: planning
|
||||
description: Decompose work into small, verifiable, ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable units.
|
||||
---
|
||||
|
||||
# Planning and Task Breakdown
|
||||
|
||||
## Overview
|
||||
|
||||
Good task breakdown is the difference between reliable delivery and a tangled mess. Every task should be small enough to implement, test, and verify in a single focused session.
|
||||
|
||||
**Input:** A spec (load `spec-driven-dev` skill) or clear requirements.
|
||||
|
||||
**Output:** A prioritized, ordered list of tasks with acceptance criteria and verification steps.
|
||||
|
||||
## When to Use
|
||||
|
||||
- You have a spec and need to break it into implementable units
|
||||
- A task feels too large or vague to start
|
||||
- You need to communicate scope to Mathias
|
||||
- The implementation order isn't obvious
|
||||
- You want to identify parallelization opportunities
|
||||
|
||||
**When NOT to use:** Single-file changes with obvious scope.
|
||||
|
||||
## The Planning Process
|
||||
|
||||
### Step 1: Read-Only Discovery
|
||||
|
||||
Before writing any tasks, operate in read-only mode:
|
||||
|
||||
- Read the spec and relevant code
|
||||
- Identify existing patterns, conventions, and infrastructure
|
||||
- Map dependencies between components
|
||||
- Note risks and unknowns
|
||||
|
||||
**Do NOT write code during planning.** The output is a plan document, not implementation.
|
||||
|
||||
### Step 2: Map the Dependency Graph
|
||||
|
||||
Visualize what depends on what:
|
||||
|
||||
```
|
||||
Database schema / migrations
|
||||
│
|
||||
├── Domain types (pure Go structs + interfaces)
|
||||
│ │
|
||||
│ ├── Service layer (business logic)
|
||||
│ │ │
|
||||
│ │ └── HTTP handlers
|
||||
│ │
|
||||
│ └── Store implementations (postgres, in-memory)
|
||||
│
|
||||
└── Seed data / test fixtures
|
||||
```
|
||||
|
||||
**Build foundations first.** You can't test a handler before the service exists. You can't write a service before the domain types are defined.
|
||||
|
||||
### Step 3: Slice Vertically
|
||||
|
||||
Build one complete feature path at a time, not one layer at a time.
|
||||
|
||||
**Bad (horizontal slicing):**
|
||||
```
|
||||
Task 1: Write all database migrations
|
||||
Task 2: Write all store implementations
|
||||
Task 3: Write all service methods
|
||||
Task 4: Write all handlers
|
||||
```
|
||||
No working software until Task 4. If Task 1 is wrong, you discover it late.
|
||||
|
||||
**Good (vertical slicing):**
|
||||
```
|
||||
Task 1: User can create an account (migration + store + service + handler for create)
|
||||
Task 2: User can log in (auth store + service + handler)
|
||||
Task 3: User can view their invoices (query + service + handler + response type)
|
||||
```
|
||||
Each task delivers working, testable functionality. If Task 1 reveals a design issue, Tasks 2+ can adapt.
|
||||
|
||||
### Step 4: Write Tasks
|
||||
|
||||
Each task follows this structure:
|
||||
|
||||
```markdown
|
||||
## Task [N]: [Short descriptive title]
|
||||
|
||||
**Description:** One sentence explaining what this task accomplishes.
|
||||
|
||||
**Acceptance criteria:**
|
||||
- [ ] [Specific, testable condition]
|
||||
- [ ] [Specific, testable condition]
|
||||
|
||||
**Verification:**
|
||||
- [ ] Tests pass: `go test -run TestFeatureName ./...`
|
||||
- [ ] Build: `go build ./...`
|
||||
- [ ] Manual check: [description if needed]
|
||||
|
||||
**Dependencies:** Task [N-1], Task [N-2] (or "None")
|
||||
|
||||
**Files likely touched:**
|
||||
- `internal/domain/user.go`
|
||||
- `internal/store/user_store.go`
|
||||
- `internal/service/user_service.go`
|
||||
|
||||
**Estimated scope:** [XS/S/M/L]
|
||||
```
|
||||
|
||||
### Step 5: Order and Add Checkpoints
|
||||
|
||||
Arrange tasks so:
|
||||
1. Dependencies are satisfied (build foundation first)
|
||||
2. Each task leaves the system in a working state
|
||||
3. High-risk tasks are early (fail fast)
|
||||
4. Checkpoints occur after every 2–3 tasks
|
||||
|
||||
```markdown
|
||||
## Checkpoint: After Tasks 1–3
|
||||
|
||||
- [ ] `go test ./...` passes
|
||||
- [ ] `go build ./...` succeeds
|
||||
- [ ] Core user flow works end-to-end (can register and log in)
|
||||
- [ ] Mathias reviews before continuing
|
||||
```
|
||||
|
||||
## Task Sizing Guidelines
|
||||
|
||||
| Size | Files | Scope | Example |
|
||||
|------|-------|-------|---------|
|
||||
| **XS** | 1 | Single function or type | Add a validation rule to User |
|
||||
| **S** | 1–2 | One endpoint or store method | Add GetByEmail to UserStore |
|
||||
| **M** | 3–5 | One feature slice | User registration (domain + store + service + handler) |
|
||||
| **L** | 5–8 | Multi-component feature | Search with filtering, pagination, and sorting |
|
||||
| **XL** | 8+ | **Too large — break it down** | — |
|
||||
|
||||
**Break any XL task into smaller tasks.** An agent performs best on XS, S, and M tasks.
|
||||
|
||||
**Break a task down further when:**
|
||||
- It would take more than 2–3 hours of focused work
|
||||
- The acceptance criteria have more than 4 bullet points
|
||||
- It touches two independent subsystems (auth AND billing in the same task)
|
||||
- You find yourself writing "and" in the task title
|
||||
|
||||
## Plan Document Template
|
||||
|
||||
```markdown
|
||||
# Implementation Plan: [Feature/Project Name]
|
||||
|
||||
## Overview
|
||||
[One paragraph: what we're building and the key technical decisions]
|
||||
|
||||
## Architecture Decisions
|
||||
- [Decision 1 and rationale]
|
||||
- [Decision 2 and rationale]
|
||||
|
||||
## Dependency Graph
|
||||
[Diagram or list showing what depends on what]
|
||||
|
||||
## Task List
|
||||
|
||||
### Phase 1: Foundation
|
||||
|
||||
- [ ] **Task 1:** [Title] — [Scope: XS/S/M]
|
||||
- AC: [criteria]
|
||||
- Verify: `go test -run TestX ./...`
|
||||
- Files: [list]
|
||||
|
||||
- [ ] **Task 2:** [Title] — [Scope: XS/S/M]
|
||||
...
|
||||
|
||||
### Checkpoint: Foundation Complete
|
||||
- [ ] `go test ./...` passes
|
||||
- [ ] Build clean
|
||||
- [ ] Foundation behavior works end-to-end
|
||||
|
||||
### Phase 2: Core Features
|
||||
|
||||
- [ ] **Task 3:** [Title] — [Scope: S/M]
|
||||
...
|
||||
|
||||
### Checkpoint: Core Features Complete
|
||||
- [ ] User-facing scenarios work
|
||||
- [ ] Mathias reviews before Phase 3
|
||||
|
||||
### Phase 3: Polish and Edge Cases
|
||||
|
||||
- [ ] **Task 5:** Handle [edge case]
|
||||
- [ ] **Task 6:** [Performance/error handling]
|
||||
|
||||
### Checkpoint: Complete
|
||||
- [ ] All acceptance criteria from the spec are met
|
||||
- [ ] `go test -race ./...` passes
|
||||
- [ ] govulncheck passes
|
||||
- [ ] Ready for review
|
||||
|
||||
## Risks and Mitigations
|
||||
|
||||
| Risk | Impact | Mitigation |
|
||||
|------|--------|-----------|
|
||||
| [External API behavior unknown] | High | Spike task first |
|
||||
| [Data volume may be larger than expected] | Medium | Add pagination before shipping |
|
||||
|
||||
## Open Questions
|
||||
- [Question requiring Mathias's input]
|
||||
```
|
||||
|
||||
## Parallelization
|
||||
|
||||
When working in parallel (multiple sessions or agents):
|
||||
|
||||
- **Safe to parallelize:** Independent feature slices, tests for already-implemented features
|
||||
- **Must be sequential:** Database migrations, shared interface changes, dependency chains
|
||||
- **Needs coordination:** Features that share an API contract — define the contract first, then parallelize
|
||||
|
||||
## Go-Specific Planning Notes
|
||||
|
||||
### Database First, Then Domain
|
||||
|
||||
If the feature requires a schema change:
|
||||
1. Write and apply migration first
|
||||
2. Generate sqlc code (`task generate` or `sqlc generate`)
|
||||
3. Then write domain types and service
|
||||
|
||||
### Interface Contracts Before Parallel Work
|
||||
|
||||
If two tasks depend on a shared interface:
|
||||
```go
|
||||
// Define this first, in its own task
|
||||
type InvoiceStore interface {
|
||||
Save(ctx context.Context, inv Invoice) error
|
||||
GetByID(ctx context.Context, id InvoiceID) (Invoice, error)
|
||||
}
|
||||
```
|
||||
|
||||
Then write the postgres implementation and the service in parallel.
|
||||
|
||||
### Spike Tasks for Unknowns
|
||||
|
||||
If a risk involves an unknown (new API, unfamiliar library, performance unknown):
|
||||
|
||||
```markdown
|
||||
## Task 0 (Spike): Validate Bankgirot API integration
|
||||
|
||||
**Description:** Verify we can submit an ISO 20022 message to Bankgirot sandbox.
|
||||
**Timebox:** 2 hours
|
||||
**Output:** Working code or decision to change approach
|
||||
**Not:** Production-quality code — throw it away after learning
|
||||
```
|
||||
|
||||
Spikes are timeboxed explorations. The code is thrown away. The learning is kept.
|
||||
|
||||
## Verification Before Starting
|
||||
|
||||
Before beginning implementation:
|
||||
|
||||
- [ ] Every task has acceptance criteria
|
||||
- [ ] Every task has a verification step
|
||||
- [ ] Task dependencies are identified and ordered correctly
|
||||
- [ ] No task touches more than ~5 files
|
||||
- [ ] Checkpoints exist between major phases
|
||||
- [ ] Mathias has reviewed and approved the plan
|
||||
|
||||
## Common Rationalizations
|
||||
|
||||
| Rationalization | Reality |
|
||||
|---|---|
|
||||
| "I'll figure it out as I go" | That's how you end up with rework. 10 minutes of planning saves hours. |
|
||||
| "The tasks are obvious" | Write them down. Explicit tasks surface hidden dependencies. |
|
||||
| "Planning is overhead" | Planning IS the task. Implementation without a plan is just typing. |
|
||||
| "I can hold it all in my head" | Context windows are finite. Written plans survive session boundaries. |
|
||||
|
||||
## Cross-References
|
||||
|
||||
- Requires: `spec-driven-dev` skill output
|
||||
- During implementation: load `tdd` skill per task
|
||||
- For large refactoring tasks: load `refactoring` skill
|
||||
- For architecture decisions: load `solid` skill
|
||||
Reference in New Issue
Block a user