Brummel
253273b007
Establishes the repository structure for the skills plugin: - README + INSTALL describing the two-layer split (plugin mechanics vs per-project profile) - docs/design, profile-schema, pipeline, agent-template covering the universal discipline constants and the profile slot model - templates/project-profile.yml as a copy-and-fill starting point - templates/CLAUDE.md.fragment with the baseline orchestrator rules a project can import - install.sh / uninstall.sh wiring skills/ + agents/ into ~/.claude/ via idempotent symlinks - skills/ and agents/ directories empty except for migration READMEs; the actual SKILL bodies and agent files migrate from ~/dev/ailang/skills/ in the next iteration. No skill or agent runs yet — this commit only stands up the structure and documents the substitution model.
151 lines
6.1 KiB
Markdown
151 lines
6.1 KiB
Markdown
# Profile schema
|
|
|
|
Location: `<project-root>/.claude/dev-cycle-profile.yml`
|
|
|
|
Encoding: YAML. Each top-level key is a section. Keys are
|
|
lowercase snake_case. Lists are YAML sequences.
|
|
|
|
## `paths`
|
|
|
|
| Key | Type | Default | Description |
|
|
|---------------------|--------|------------------------|-------------|
|
|
| `spec_dir` | string | `docs/specs` | Where the brainstorm skill writes specs. |
|
|
| `plan_dir` | string | `docs/plans` | Where the planner skill writes plans. |
|
|
| `design_ledger` | string | `design/INDEX.md` | Canonical specification index (optional — projects without a design ledger can omit). |
|
|
| `design_contracts` | string | `design/contracts` | Directory of prose-authoritative contracts (optional). |
|
|
| `design_models` | string | `design/models` | Directory of onboarding whitepapers (optional). |
|
|
| `code_roots` | list | `[src]` | Code directories the architect / quality reviewer walk. |
|
|
| `bench_dir` | string | `bench` | Where regression harnesses live (optional). |
|
|
|
|
Omitted optional keys signal that the feature is unused in this
|
|
project; skills that depend on them either short-circuit or
|
|
skip the corresponding step.
|
|
|
|
## `naming`
|
|
|
|
| Key | Type | Default | Description |
|
|
|--------------------|--------|----------------------------------|-------------|
|
|
| `counter_dirs` | list | `[]` | Directories that use the counter-prefix policy. |
|
|
| `policy` | enum | `flat` | One of `stable_per_directory_4digit`, `date_prefix`, `flat`. |
|
|
| `slug_separator` | string | `-` | Separator inside the slug. |
|
|
|
|
`stable_per_directory_4digit` means each listed directory has a
|
|
per-directory counter, 4-digit zero-padded, assigned in
|
|
creation order, stable for the life of the file. New files
|
|
take the next-higher number; deleted files retire their number.
|
|
|
|
`date_prefix` uses `YYYY-MM-DD-slug.md`.
|
|
|
|
`flat` uses `slug.md`.
|
|
|
|
## `commands`
|
|
|
|
| Key | Type | Default | Description |
|
|
|----------------|--------|----------------|-------------|
|
|
| `build` | string | (required) | Build command — exit 0 means success. |
|
|
| `test` | string | (required) | Test command — exit 0 means success. |
|
|
| `lint` | string | (optional) | Lint command — exit 0 means success. |
|
|
| `regression` | list | `[]` | Regression scripts run by the audit skill. Each entry is a shell command; non-zero exit is a regress. |
|
|
|
|
## `vocabulary`
|
|
|
|
| Key | Type | Default | Description |
|
|
|----------------|--------|----------------|-------------|
|
|
| `cycle` | string | `cycle` | What a top-level work unit is called. Examples: `milestone`, `release`, `epic`. |
|
|
| `subcycle` | string | `iteration` | What a sub-unit is called. Examples: `iteration`, `sprint`, `story`. |
|
|
| `ledger_entry` | string | `contract` | What a single design-ledger entry is called. Examples: `contract`, `RFC`, `ADR`. |
|
|
|
|
Skills use these names in their generated artefacts and prose.
|
|
Picking accurate vocabulary keeps prose readable; the underlying
|
|
mechanics are identical regardless of name.
|
|
|
|
## `standing_reading`
|
|
|
|
| Key | Type | Default | Description |
|
|
|----------------|--------|----------------|-------------|
|
|
| `always` | list | `[CLAUDE.md]` | Files every agent reads at start of every dispatch. |
|
|
| `by_role` | map | `{}` | Map from role name to list of additional files. |
|
|
|
|
Role names match agent slugs: `architect`, `bencher`, `debugger`,
|
|
`implementer`, `tester`, `fieldtester`, `docwriter`,
|
|
`grounding-check`, `plan-recon`, `spec-reviewer`, `quality-reviewer`.
|
|
|
|
Entries may be shell commands as well as file paths — they are
|
|
read as opaque strings the agent should fetch / execute, e.g.
|
|
`"git log -10 --format=full"`.
|
|
|
|
## `git`
|
|
|
|
| Key | Type | Default | Description |
|
|
|------------------------------|------|---------|-------------|
|
|
| `main_sacrosanct` | bool | `true` | If true, no actor may reset or revert main. |
|
|
| `only_orchestrator_commits` | bool | `true` | If true, no agent commits; the orchestrator commits. |
|
|
| `issue_tracker.kind` | enum | `none` | One of `gitea`, `github`, `linear`, `none`. |
|
|
| `issue_tracker.close_marker` | string | `"closes #N"` | Marker the orchestrator includes in commit bodies to auto-close issues. |
|
|
| `protected_branches` | list | `[main]` | Branches that are sacrosanct in the same sense as main. |
|
|
|
|
## `pipeline`
|
|
|
|
Per-phase configuration. Each phase has its own sub-map.
|
|
|
|
```yaml
|
|
pipeline:
|
|
brainstorm:
|
|
gates: [planner] # planner cannot start until this has run
|
|
planner:
|
|
gates: [implement]
|
|
implement: {} # standard
|
|
audit:
|
|
mandatory_at: cycle_close # auto-fires at end of each cycle
|
|
fieldtest:
|
|
boss_only: true # only orchestrator dispatches
|
|
when: surface_touch # condition tag (orchestrator judgement)
|
|
docwriter:
|
|
boss_only: true
|
|
when: api_stable_across_n_cycles
|
|
debug:
|
|
trigger: bug # observable misbehaviour
|
|
red_first: true # RED test before any fix
|
|
```
|
|
|
|
Phases not listed are disabled for the project. A project that
|
|
does not want a `fieldtest` phase simply omits the key.
|
|
|
|
## Example: minimal profile
|
|
|
|
```yaml
|
|
paths:
|
|
spec_dir: docs/specs
|
|
plan_dir: docs/plans
|
|
code_roots: [src]
|
|
|
|
commands:
|
|
build: cargo build
|
|
test: cargo test
|
|
|
|
vocabulary:
|
|
cycle: milestone
|
|
subcycle: iteration
|
|
|
|
standing_reading:
|
|
always:
|
|
- CLAUDE.md
|
|
- "git log -10 --format=full"
|
|
|
|
git:
|
|
issue_tracker:
|
|
kind: github
|
|
close_marker: "closes #N"
|
|
|
|
pipeline:
|
|
brainstorm: { gates: [planner] }
|
|
planner: { gates: [implement] }
|
|
implement: {}
|
|
audit: { mandatory_at: cycle_close }
|
|
debug: { trigger: bug, red_first: true }
|
|
```
|
|
|
|
This minimal profile enables five phases, no fieldtest, no
|
|
docwriter, no design-ledger. Good starting point for a small
|
|
project.
|