initial commit
This commit is contained in:
Jev Kuznetsov
@@ -0,0 +1,10 @@
|
||||
---
|
||||
name: implementer
|
||||
description: Implement a feature by writing tests, production code, and committing changes. Delegates from /develop.
|
||||
model: sonnet
|
||||
tools: Read, Edit, Write, Bash, Grep, Glob
|
||||
skills:
|
||||
- commit
|
||||
---
|
||||
|
||||
Read only the minimum files needed. Write tests first, then production code. Commit atomically as you go using conventional commits. Run tests after each logical step. If stuck after 3 attempts on the same issue, report `[BLOCKED: reason]`.
|
||||
@@ -0,0 +1,31 @@
|
||||
## Role
|
||||
Senior Python developer assistant. Optimize for simple, maintainable code and low-token responses.
|
||||
|
||||
## Behavior
|
||||
- Act on requests by default.
|
||||
- Ask questions only if ambiguity affects correctness.
|
||||
- Keep scope tight; do not add unrequested features.
|
||||
- Propose a short plan (≤5 bullets) only when useful.
|
||||
- If a request overcomplicates things, call it out and suggest a simpler option.
|
||||
- Commit only when explicitly asked.
|
||||
|
||||
## Principles
|
||||
- KISS, YAGNI.
|
||||
- Explicit > implicit; readability counts.
|
||||
- Flat > nested; avoid deep abstractions.
|
||||
- Sparse > dense; avoid clever one-liners.
|
||||
- No speculative patterns or overengineering.
|
||||
|
||||
## Coding
|
||||
- Python 3.10+ with type hints (PEP 604).
|
||||
- Use `uv`
|
||||
- Clear names; short docstrings for non-obvious parts.
|
||||
- No placeholders unless immediately needed.
|
||||
- Keep files ~300–500 lines when practical.
|
||||
- Keep imports at top.
|
||||
|
||||
## Sub-agents
|
||||
- Read minimum required files.
|
||||
- Return concise summaries, not raw dumps.
|
||||
- Treat as stateless; don’t pass full context unless needed.
|
||||
- Don’t use for simple search or git tasks.
|
||||
@@ -0,0 +1,16 @@
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(uv sync:*)",
|
||||
"Bash(uv run pytest:*)",
|
||||
"Bash(inv lint:*)",
|
||||
"Bash(inv test:*)"
|
||||
],
|
||||
"deny": [
|
||||
"Read(./.venv/**)",
|
||||
"Read(./__pycache__/**)",
|
||||
"Read(./.env*)"
|
||||
]
|
||||
},
|
||||
"skipDangerousModePermissionPrompt": true
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
name: architect
|
||||
description: Create or update docs/architecture.md from user stories and project context.
|
||||
---
|
||||
|
||||
# Architect
|
||||
|
||||
Produce `docs/architecture.md`.
|
||||
|
||||
## Process
|
||||
|
||||
1. Read `docs/user_stories.md` and any existing `docs/architecture.md`.
|
||||
2. Produce or update `docs/architecture.md` using the template in `assets/template.md`.
|
||||
|
||||
## Rules
|
||||
|
||||
- Make reasonable assumptions and flag each with `[ASSUMPTION]`.
|
||||
- Ask only if a missing answer would materially change the architecture and cannot be inferred.
|
||||
- Keep the document as short as reasonably possible.
|
||||
- Mermaid diagrams only.
|
||||
- Be specific: version numbers, concrete patterns, no "best practices" filler.
|
||||
- If updating an existing document, preserve decisions that are still valid.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Architecture: [Project Name]
|
||||
|
||||
## Problem and context
|
||||
What problem this solves and for whom.
|
||||
|
||||
## Goals and non-goals
|
||||
Numbered goals with measurable criteria. Explicit non-goals.
|
||||
|
||||
## Repository structure
|
||||
Directory layout with one-line descriptions.
|
||||
|
||||
## System overview
|
||||
One paragraph, then a Mermaid component diagram showing major components,
|
||||
responsibilities, and communication paths.
|
||||
|
||||
## Technology stack
|
||||
| Component | Technology | Version | Rationale |
|
||||
|
||||
## Module boundaries
|
||||
For each module: what it owns, its public interface, and what it must NOT do.
|
||||
Communication patterns between modules (sync/async, events, RPC).
|
||||
|
||||
## Key architectural decisions
|
||||
For each important decision:
|
||||
- **Decision:** what was chosen
|
||||
- **Alternatives considered:** what else was evaluated
|
||||
- **Rationale:** why this option
|
||||
|
||||
## Constraints and conventions
|
||||
Tech stack rules, naming conventions, forbidden libraries, project-wide patterns.
|
||||
|
||||
## Open questions
|
||||
Only unresolved items that must be decided later.
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
name: commit
|
||||
description: Stage and commit changes on the active feature branch using atomic conventional commits.
|
||||
---
|
||||
|
||||
# Commit
|
||||
|
||||
Create atomic conventional commits on the active feature branch.
|
||||
|
||||
## Commit format
|
||||
|
||||
- Format: `type(scope): description`
|
||||
- Types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`
|
||||
- First line: imperative mood, lowercase, concise (e.g., "add login" not "added login").
|
||||
- Body: only for complex changes; explain why, not what.
|
||||
- Footer: `BREAKING CHANGE:` if applicable.
|
||||
|
||||
## Rules
|
||||
|
||||
- Scope is optional but encouraged when a module or file is the clear focus.
|
||||
- If changes span multiple logical tasks, create separate commits.
|
||||
- Each commit must be independently reviewable.
|
||||
- Never combine unrelated changes in a single commit.
|
||||
Executable
+61
@@ -0,0 +1,61 @@
|
||||
#!/usr/bin/env bash
|
||||
# Stage specified files and create a commit.
|
||||
# Usage: bash scripts/commit.sh --message "type(scope): description" [--] file1 file2 ...
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
usage() {
|
||||
echo "Usage: bash scripts/commit.sh --message MESSAGE [--] FILE [FILE...]"
|
||||
echo ""
|
||||
echo "Options:"
|
||||
echo " --message MESSAGE Commit message (required)"
|
||||
echo " --help Show this help"
|
||||
echo ""
|
||||
echo "Examples:"
|
||||
echo " bash scripts/commit.sh --message \"feat(auth): add login endpoint\" src/auth.py tests/test_auth.py"
|
||||
echo " bash scripts/commit.sh --message \"chore: update deps\" -- requirements.txt"
|
||||
}
|
||||
|
||||
MESSAGE=""
|
||||
FILES=()
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--help) usage; exit 0 ;;
|
||||
--message)
|
||||
[[ -z "${2:-}" ]] && { echo "Error: --message requires a value."; exit 1; }
|
||||
MESSAGE="$2"; shift 2 ;;
|
||||
--) shift; FILES+=("$@"); break ;;
|
||||
-*) echo "Error: unknown option '$1'. Run with --help for usage."; exit 1 ;;
|
||||
*) FILES+=("$1"); shift ;;
|
||||
esac
|
||||
done
|
||||
|
||||
CURRENT_BRANCH="$(git branch --show-current)"
|
||||
|
||||
if [[ -z "$CURRENT_BRANCH" ]]; then
|
||||
echo "Error: not on a branch."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" ]]; then
|
||||
echo "Error: refusing to commit directly on '$CURRENT_BRANCH'. Create or switch to a feature branch first."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ -z "$MESSAGE" ]]; then
|
||||
echo "Error: --message is required."
|
||||
echo ""
|
||||
usage
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ ${#FILES[@]} -eq 0 ]]; then
|
||||
echo "Error: at least one file must be specified."
|
||||
echo ""
|
||||
usage
|
||||
exit 1
|
||||
fi
|
||||
|
||||
git add -- "${FILES[@]}"
|
||||
git commit --message "$MESSAGE"
|
||||
Executable
+36
@@ -0,0 +1,36 @@
|
||||
#!/usr/bin/env bash
|
||||
# Show branch status and full diff for commit planning.
|
||||
# Usage: bash scripts/status.sh [BASE_BRANCH]
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
if [[ "${1:-}" == "--help" ]]; then
|
||||
echo "Usage: bash scripts/status.sh [BASE_BRANCH]"
|
||||
echo ""
|
||||
echo "Prints the current branch, git status, and the full diff (staged and unstaged) for commit planning."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
BASE_BRANCH="${1:-main}"
|
||||
CURRENT_BRANCH="$(git branch --show-current)"
|
||||
|
||||
echo "=== current branch ==="
|
||||
echo "${CURRENT_BRANCH:-detached HEAD}"
|
||||
|
||||
if git rev-parse --verify "$BASE_BRANCH" >/dev/null 2>&1 && [[ -n "$CURRENT_BRANCH" && "$CURRENT_BRANCH" != "$BASE_BRANCH" ]]; then
|
||||
echo ""
|
||||
echo "=== commits ahead of $BASE_BRANCH ==="
|
||||
git --no-pager log --oneline "$BASE_BRANCH..$CURRENT_BRANCH"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== git status ==="
|
||||
git status --short --branch
|
||||
|
||||
echo ""
|
||||
echo "=== staged diff ==="
|
||||
git diff --staged
|
||||
|
||||
echo ""
|
||||
echo "=== unstaged diff ==="
|
||||
git diff
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
name: develop
|
||||
description: "Autopilot feature delivery: spec, implement, commit, review — stops for manual testing before merge."
|
||||
---
|
||||
|
||||
# Develop
|
||||
|
||||
Deliver a feature end-to-end with minimal human intervention.
|
||||
|
||||
## Input
|
||||
|
||||
`/develop <description>` — a plain-English feature description or slug name.
|
||||
|
||||
If no description is provided:
|
||||
1. Read `docs/feature_backlog.md` if it exists.
|
||||
2. Pick the first `## NNN — title` item (lowest `NNN`).
|
||||
3. Announce: "Next up: **NNN — title** — description. Starting now." then proceed.
|
||||
4. If no backlog exists, ask: "What should I build?" and wait.
|
||||
|
||||
## Resuming an interrupted run
|
||||
|
||||
1. Run `git log --oneline` to see commits on the branch.
|
||||
2. Check `Status` in `docs/features/<NNN-slug>.md`.
|
||||
3. Skip completed phases, continue from the next one.
|
||||
|
||||
## Phase 0 — Setup
|
||||
|
||||
1. Derive a slug from the description (e.g. `user-auth`, `csv-export`).
|
||||
2. Determine the numeric prefix: list files in `docs/features/` matching `[0-9][0-9][0-9]-*.md`, find the highest number, and use one higher. If no files exist, start at `001`. Format: `NNN-<slug>` (e.g. `001-user-auth`, `042-csv-export`).
|
||||
3. Use the full prefixed slug everywhere: branch name (`feat/NNN-<slug>`), spec file (`docs/features/NNN-<slug>.md`), and commit messages.
|
||||
4. Run `git checkout -b feat/<NNN-slug>` to create the feature branch. If it already exists, switch to it.
|
||||
5. If the working tree is dirty, stash changes first with `git stash`, then pop after switching.
|
||||
|
||||
## Phase 1 — Spec
|
||||
|
||||
1. Read `docs/architecture.md` if it exists (not required).
|
||||
2. Write a lightweight feature spec to `docs/features/<NNN-slug>.md` using the template in `assets/spec-template.md`.
|
||||
3. Make reasonable assumptions — flag each with `[ASSUMPTION]` in the spec.
|
||||
4. Ask only if a missing answer would materially change the result and cannot be inferred. Otherwise choose the simpler option and flag it.
|
||||
5. Commit the spec: `docs(<NNN-slug>): add feature spec`
|
||||
|
||||
## Phase 2 — Implement + Commit
|
||||
|
||||
Delegate to the **implementer** subagent (Sonnet). Provide it with:
|
||||
- The feature spec path
|
||||
- The architecture doc path (if it exists)
|
||||
- Instruction to write tests first, then production code
|
||||
- Instruction to commit atomically as it goes (conventional commits)
|
||||
- Instruction to run tests after each logical step
|
||||
- Instruction to read only the minimum files needed
|
||||
|
||||
If the implementer reports `[BLOCKED]`, stop and report the blocker to the user.
|
||||
|
||||
**Copilot / single-thread mode:** run implementation directly — read the spec, write tests, implement, commit, run tests.
|
||||
|
||||
## Phase 3 — Review
|
||||
|
||||
1. Run the test suite (`inv test` or project-appropriate test command).
|
||||
2. Run `git diff main...HEAD` to see all changes on the feature branch.
|
||||
3. Compare against the feature spec:
|
||||
- Are all acceptance criteria addressed?
|
||||
- Do tests pass?
|
||||
- Any obvious issues (broken imports, missing files, dead code)?
|
||||
4. Decision:
|
||||
- **PASS** → update spec status to `approved`. Stop and tell the user: "Feature branch `feat/<NNN-slug>` is ready. Test it, then run `/merge <NNN-slug>` to merge."
|
||||
- **FIXABLE** → loop back to Phase 2 with specific fix instructions. Maximum **1 retry**.
|
||||
- **BLOCKED** → update spec status to `blocked`, stop and report to user.
|
||||
|
||||
## When to stop
|
||||
|
||||
Stop and report to the user ONLY for:
|
||||
- Contradictions between the feature description and existing architecture
|
||||
- Test failures that can't be resolved after 3 attempts
|
||||
- Merge conflicts that can't be auto-resolved
|
||||
- Missing critical information that genuinely cannot be assumed
|
||||
|
||||
Do NOT stop for:
|
||||
- Choosing between implementation approaches (pick the simpler one, flag with `[ASSUMPTION]`)
|
||||
- Creating new files or modules (just do it)
|
||||
- Commit message wording (use conventional commits)
|
||||
|
||||
## Rules
|
||||
|
||||
- No approval gates.
|
||||
- Make assumptions and flag them.
|
||||
- Atomic conventional commits throughout.
|
||||
- Feature branches are temporary — created and merged automatically.
|
||||
- If the project has no test infrastructure, skip test-related steps and note it in the review.
|
||||
@@ -0,0 +1,23 @@
|
||||
# Feature: <Name>
|
||||
|
||||
Status: draft
|
||||
|
||||
## Summary
|
||||
|
||||
One sentence: what this feature does and why it's needed.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- AC-01: ...
|
||||
|
||||
## Test Plan
|
||||
|
||||
- T-01 (AC-01): given ... / when ... / then ...
|
||||
|
||||
## Assumptions
|
||||
|
||||
- [ASSUMPTION]: ...
|
||||
|
||||
## Notes
|
||||
|
||||
Optional: implementation hints, constraints, edge cases.
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
name: merge
|
||||
description: "Merge a reviewed feature branch to main and clean up."
|
||||
---
|
||||
|
||||
# Merge
|
||||
|
||||
Merge a completed feature branch into `main` and delete it.
|
||||
|
||||
## Input
|
||||
|
||||
`/merge <NNN-slug>` — the prefixed feature slug (e.g. `042-csv-export`).
|
||||
|
||||
If no slug is provided, check the current branch (`git branch --show-current`). If it matches `feat/<NNN-slug>`, derive the slug from it. Otherwise, list feature branches and ask: "Which branch should I merge?"
|
||||
|
||||
## Steps
|
||||
|
||||
1. Confirm the feature spec at `docs/features/<NNN-slug>.md` has status `approved`. If not, stop and report.
|
||||
2. `git checkout main`
|
||||
3. `git merge --no-ff feat/<NNN-slug>`
|
||||
4. If merge conflicts occur, attempt auto-resolution. If that fails, stop and report the conflicting files.
|
||||
5. `git branch -d feat/<NNN-slug>`
|
||||
6. Report summary: feature name, number of commits merged, what was built.
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
name: review
|
||||
description: Audit the full codebase as a software architect. Score on 5 KPIs (Maintainability, Extensibility, Testability, Robustness, Clarity) and produce docs/review.md.
|
||||
---
|
||||
|
||||
# Review
|
||||
|
||||
Audit the codebase, score each KPI 0–10, and produce `docs/review.md`.
|
||||
|
||||
## Process
|
||||
|
||||
1. Run the test suite to verify baseline health and gather coverage stats.
|
||||
2. Analyze the codebase against the 5 KPIs below.
|
||||
3. Produce `docs/review.md` using the template in `assets/template.md`.
|
||||
|
||||
## KPIs
|
||||
|
||||
1. **Maintainability** — How easily can the system be debugged, modified, or understood?
|
||||
Metrics: modularity, cohesion, coupling, readability, simplicity.
|
||||
|
||||
2. **Extensibility** — How easily can new features be added without major refactoring?
|
||||
Metrics: separation of concerns, dependency injection, use of interfaces/protocols.
|
||||
|
||||
3. **Testability** — How easily can components be tested in isolation and as a whole?
|
||||
Metrics: pure functions, mockability, dependency inversion.
|
||||
|
||||
4. **Robustness** — How well does the system handle edge cases, errors, and real-world conditions?
|
||||
Metrics: state management, predictability, fault tolerance.
|
||||
|
||||
5. **Clarity** — How quickly can a new developer understand the system's design and purpose?
|
||||
Metrics: documentation, consistent naming, clear abstractions.
|
||||
|
||||
## Rules
|
||||
|
||||
- Be specific — cite `file:line` or `file:function` when pointing out issues.
|
||||
- No filler — every bullet must be actionable or informative.
|
||||
- Always include your model/version in the reviewer field.
|
||||
- Do not modify any code. This is a read-only review.
|
||||
- Keep the write-up concise.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Code Review
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Date | YYYY-MM-DD |
|
||||
| Reviewer | model name and version |
|
||||
| LOC | total lines of code |
|
||||
| Tests | count |
|
||||
| Coverage | percentage (if available) |
|
||||
|
||||
## Maintainability — X/10
|
||||
- ...
|
||||
|
||||
## Extensibility — X/10
|
||||
...
|
||||
|
||||
## Testability — X/10
|
||||
...
|
||||
|
||||
## Robustness — X/10
|
||||
...
|
||||
|
||||
## Clarity — X/10
|
||||
...
|
||||
|
||||
## Summary
|
||||
One short paragraph on the overall state of the codebase.
|
||||
|
||||
## Priority recommendations
|
||||
Top 5 actionable improvements, ordered by impact.
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
name: wbs
|
||||
description: Break down architecture.md into a prioritized feature backlog, skipping already-built features.
|
||||
---
|
||||
|
||||
# Plan
|
||||
|
||||
Produce or update `docs/feature_backlog.md`.
|
||||
|
||||
## Process
|
||||
|
||||
1. Read `docs/architecture.md`. This is the source of truth for what needs to be built.
|
||||
2. Scan `docs/features/` for existing feature spec files (pattern: `[0-9][0-9][0-9]-*.md`). These are already built — do not include them in the backlog.
|
||||
3. Find the highest `NNN` number across both `docs/features/` files and any existing `docs/feature_backlog.md` entries. New items start from one higher.
|
||||
4. Produce `docs/feature_backlog.md` with this structure:
|
||||
|
||||
```markdown
|
||||
# Feature Backlog
|
||||
|
||||
Completed features are tracked in `docs/features/` and removed from this list.
|
||||
|
||||
---
|
||||
|
||||
## NNN — slug-style-title
|
||||
|
||||
One sentence describing what gets built.
|
||||
|
||||
## NNN — next-item
|
||||
|
||||
One sentence. Optionally:
|
||||
depends: NNN
|
||||
```
|
||||
|
||||
## What goes on the backlog
|
||||
|
||||
Cover everything in the architecture that is not yet implemented. Group logically — infrastructure first, then features, then integrations.
|
||||
|
||||
Do not add items for:
|
||||
- Work already represented by a file in `docs/features/`
|
||||
- Documentation, comments, or cleanup unless explicitly in the architecture
|
||||
- Vague future ideas not grounded in the architecture
|
||||
|
||||
## Chunk sizing
|
||||
|
||||
Each backlog item will be handed to a coding agent that writes a spec, implements the code, and commits — all in one automated pass with no human in the loop. Size items accordingly:
|
||||
|
||||
- **Self-contained**: scope should contain a single functionality that can be implemented and tested.
|
||||
- **Scoped**: touches at most 2 modules and adds roughly 50–200 lines of production code
|
||||
- **Testable**: success is checkable by running the test suite — no manual inspection required
|
||||
|
||||
If an architectural feature is large, split it into ordered items (e.g. `data model`, then `API layer`, then `UI`).
|
||||
If a feature is trivial (a single function or config value), merge it with a related item.
|
||||
|
||||
If an item depends on another, note it on a second line as `depends: NNN`.
|
||||
|
||||
## Rules
|
||||
|
||||
- Ask only if a trade-off materially changes scope or ordering and cannot be resolved from the architecture.
|
||||
- Preserve items already in `docs/feature_backlog.md` that are not yet in `docs/features/` — only add, reorder, or remove items, do not rewrite existing descriptions without good reason.
|
||||
- Each item is a `## NNN — slug-style-title` subheading followed by one sentence (and optionally a `depends:` line).
|
||||
- Keep descriptions to one sentence — just enough for the coding agent to understand the scope.
|
||||
- Do not mark any item as done. Completed work is tracked in `docs/features/`, not here.
|
||||
Reference in New Issue
Block a user