Files

T

Brummel 253273b007 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.

2026-05-28 14:20:13 +02:00

5.0 KiB

Raw Blame History

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.

5.0 KiB Raw Blame History