skeleton: plugin layout + docs, skill/agent migration deferred to iter 1
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.
This commit is contained in:
+120
@@ -0,0 +1,120 @@
|
||||
# Design
|
||||
|
||||
## Why split plugin from profile
|
||||
|
||||
The skills system originally evolved inside the AILang project,
|
||||
where it grew organically against AILang's specific paths,
|
||||
build commands, vocabulary, and contracts. Lifting it into a
|
||||
plugin requires a clean separation between what is universal
|
||||
(belongs in the plugin) and what is project-specific (belongs
|
||||
in a per-project profile).
|
||||
|
||||
The litmus test: would a sentence in a SKILL or agent body
|
||||
still make sense in a Python web project, a Rust CLI, and a
|
||||
TypeScript library? If yes, plugin. If it mentions `cargo`,
|
||||
`crates/`, `design/INDEX.md`, `Form A`, or any project-specific
|
||||
identifier, it goes to the profile (as a slot) or to the
|
||||
project's `CLAUDE.md` (as sittenkodex).
|
||||
|
||||
## Plugin layer (universal)
|
||||
|
||||
The plugin owns:
|
||||
|
||||
- **Pipeline form** — the directed graph of phases:
|
||||
`design → plan → execute → review → close`, with the
|
||||
bug-driven side path `debug → execute (mini)`.
|
||||
- **Hard-gates** — spec before plan, plan before implement,
|
||||
audit before cycle-close. Skipping rules are codified per
|
||||
skill.
|
||||
- **Agent template** — every agent file follows the same
|
||||
structure: frontmatter (name, description, tools), Iron Law,
|
||||
standing reading list, numbered process, status protocol,
|
||||
output format, common rationalisations, red flags.
|
||||
- **TDD as an independent inner-loop discipline** — the
|
||||
implementer agent carries TDD even when the plan task forgot
|
||||
to script a RED-first step.
|
||||
- **RED-first bug fixes** — non-negotiable for any observable
|
||||
misbehaviour; the debug skill is the gate.
|
||||
- **Status protocol** — `DONE / DONE_WITH_CONCERNS / PARTIAL /
|
||||
BLOCKED / NEEDS_CONTEXT`, plus reviewer-specific terminal
|
||||
states.
|
||||
- **Working-tree-as-quarantine** — agents write artefacts to
|
||||
the working tree, never commit. Only the orchestrator commits.
|
||||
- **main HEAD sacrosanct** — no reset, no revert, by any actor.
|
||||
main moves forward only via orchestrator commits.
|
||||
- **No nested subagent dispatch** — a hard Claude Code
|
||||
platform constraint; the implement-orchestrator runs phases
|
||||
as sequential role-switches inside its own context.
|
||||
- **No orphan agents** — every agent lives under the skill
|
||||
that dispatches it.
|
||||
- **Output budget discipline** — agents have word budgets on
|
||||
their reports.
|
||||
|
||||
## Profile layer (project-specific)
|
||||
|
||||
The profile fills slots that the plugin's prose references
|
||||
generically. Concretely:
|
||||
|
||||
- **Paths**: `spec_dir`, `plan_dir`, `design_ledger`,
|
||||
`design_contracts`, `design_models`, `code_roots`, `bench_dir`.
|
||||
- **Commands**: `build`, `test`, `lint`, `regression` (list).
|
||||
- **Vocabulary**: `cycle`, `subcycle`, `ledger_entry`.
|
||||
- **Naming**: `counter_dirs`, `policy` (`stable_per_directory_4digit`
|
||||
or `date_prefix` or `flat`).
|
||||
- **Standing reading**: `always` (a list), `by_role` (a map
|
||||
from role to list).
|
||||
- **Git**: `main_sacrosanct` (bool, default true),
|
||||
`only_orchestrator_commits` (bool, default true),
|
||||
`issue_tracker.kind` (`gitea` / `github` / `linear` / `none`),
|
||||
`issue_tracker.close_marker` (e.g. `"closes #N"`).
|
||||
- **Pipeline customisations**: per-phase `mandatory_before`,
|
||||
`mandatory_at`, `boss_only`, `when` (a condition tag).
|
||||
|
||||
The full schema lives in `profile-schema.md`. The functional
|
||||
starting template is `../templates/project-profile.yml`.
|
||||
|
||||
## Resolution model
|
||||
|
||||
The plugin uses **profile-driven prompts**, not template
|
||||
rendering. Each SKILL.md and agent file is generic prose that
|
||||
references the profile prosaically:
|
||||
|
||||
> Write the spec to the directory configured under `paths.spec_dir`
|
||||
> in the project profile. Use the naming policy configured under
|
||||
> `naming.policy`.
|
||||
|
||||
When Claude Code loads the skill, the project profile is in
|
||||
context (the skill body explicitly instructs the model to read
|
||||
it first). The model performs the substitution at read-time.
|
||||
This avoids a build step and keeps a single source of truth in
|
||||
the repo.
|
||||
|
||||
## Sittenkodex split
|
||||
|
||||
The plugin does **not** carry project-specific anti-patterns,
|
||||
feature-acceptance gates, or domain contracts. Those belong in
|
||||
the project's own `CLAUDE.md`. The plugin only carries the
|
||||
*universal* discipline constants (only-orchestrator commits,
|
||||
main sacrosanct, no orphan agents, agents-don't-call-agents)
|
||||
which are conditions for the plugin's own correctness.
|
||||
|
||||
The relationship:
|
||||
|
||||
- **Plugin** (this repo): mechanics, universal discipline
|
||||
- **Profile** (per project): slots — paths, commands,
|
||||
vocabulary, naming, git conventions, pipeline customisations
|
||||
- **Project CLAUDE.md**: sittenkodex — domain-specific anti-
|
||||
patterns and acceptance criteria
|
||||
|
||||
## What's out of scope for this plugin
|
||||
|
||||
- **Boss/autonomous-orchestrator mode**: AILang's `boss` skill
|
||||
is gated to a user-invoked `/boss` for autonomous queue
|
||||
execution. Whether that generalises across projects is
|
||||
unclear (queue mechanics depend on issue-tracker semantics).
|
||||
Not in the initial skeleton; possibly added later as
|
||||
`skills/boss/` if a cross-project autonomous mode crystallises.
|
||||
- **Issue-tracker integration**: the plugin can read the
|
||||
profile's `issue_tracker.kind` and adjust commit-marker
|
||||
suggestions, but does not directly call Gitea / GitHub /
|
||||
Linear APIs.
|
||||
Reference in New Issue
Block a user