switch to ~/dev/skills/ plugin: retire in-tree skills/
The skill system migrated to a standalone plugin (http://192.168.178.103:3000/Brummel/Skills.git, local clone at ~/dev/skills/) during this branch's earlier commits. AILang now consumes the plugin via: - ~/.claude/skills/<name> and ~/.claude/agents/<name> symlinks created by ~/dev/skills/install.sh (user-level, installed once, visible from any project). - A project profile at .claude/dev-cycle-profile.yml declaring paths, commands, vocabulary, naming policy, issue tracker, notification command, and pipeline customisations. Changes: - ADD .claude/dev-cycle-profile.yml — AILang's profile against the plugin's schema (paths spec_dir/plan_dir/design_ledger/ design_contracts/design_models/code_roots/bench_dir/ public_interface/fieldtest_examples; counter-prefix naming policy; cargo build/test/doc commands; bench/check.py + compile_check.py + cross_lang.py as regression; bench/ architect_sweeps.sh as architect sweep; milestone/iteration/ contract vocabulary; design-ledger walk + git-log standing reading; bencher gets concrete RC/bump reading paths; Gitea issue-tracker URL + tea list_cmd; ~/.claude/notify.sh as notification command; the full eight-skill pipeline). - REMOVE skills/ in-tree (21 files: 7 SKILL.md + 13 agent files + skills/README.md). All eight skills + all twelve agents now live in ~/dev/skills/ as generic prose that reads slots from the profile. - REMOVE .claude/skills/ + .claude/agents/ symlinks (15 symlinks). User-level ~/.claude/skills/ + ~/.claude/agents/ installed by the plugin take over discovery. - UPDATE CLAUDE.md: * Skill-system section rewritten to point at ~/dev/skills/ + the profile file. * "My role: orchestrator" agent names dropped the ailang- prefix (implementer, tester, debugger, architect). * "Authority over `skills/`" became "Authority over the skill plugin" — naming where plugin edits vs profile vs CLAUDE.md edits live. * Bug-fixes-TDD pointer updated to ~/dev/skills/debug. * Milestone-cycle section notes the cycle/iteration vocabulary mapping the profile carries. * design-ledger-roles paragraph dropped the `ailang-` prefix on the architect agent name. * Code-layout table's `skills/` row replaced with a row describing .claude/dev-cycle-profile.yml. * ADDED a new "Lockstep-invariant pairs" section enumerating AILang's two known cross-file pairings (Pattern::Lit::* / pre_desugar_validation; lower_app / is_static_callee) — the architect agent's drift walk and plan-recon's cross-reference column both consult this section per the plugin's templates/CLAUDE.md.fragment shape. After this commit, AILang no longer ships any skill files in its own tree. All discipline lives in ~/dev/skills/; all project-specific calibration lives in .claude/dev-cycle-profile.yml plus CLAUDE.md.
This commit is contained in:
@@ -52,7 +52,7 @@ it measurably improves correctness or removes redundancy.
|
||||
| `examples/` | AILang fixtures used by tests and benches |
|
||||
| `design/` | The canonical contract ledger — `design/INDEX.md` (sole addressable spine: a typed Contracts + Models table), `design/contracts/` (prose-authoritative test-linked invariants), `design/models/` (onboarding whitepapers). Files under `contracts/` and `models/` follow the counter-prefix convention (see "File-naming convention" below). |
|
||||
| `docs/` | Specs and plans — `docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `PROSE_ROUNDTRIP.md`. Files under `specs/` and `plans/` follow the counter-prefix convention (see "File-naming convention" below). Project history lives in `git log`; the forward queue lives in Gitea issues (see "Roles" section below). |
|
||||
| `skills/` | Project-local skill definitions and their agents. See `skills/README.md` for the skill table, agent roster, and discovery layout. |
|
||||
| `.claude/dev-cycle-profile.yml` | Project profile consumed by the `~/dev/skills/` plugin — declares paths, commands, vocabulary, naming policy, issue tracker, and pipeline customisations. See `~/dev/skills/docs/profile-schema.md` for the slot reference. |
|
||||
|
||||
## File-naming convention
|
||||
|
||||
@@ -85,29 +85,39 @@ ordering.
|
||||
|
||||
## Skill system
|
||||
|
||||
Day-to-day discipline lives under `skills/<name>/SKILL.md`; see
|
||||
`skills/README.md` for the trigger table and skipping rules. Skills
|
||||
are sharper tools, not a replacement for orchestrator judgement.
|
||||
Specs go to `docs/specs/<milestone>.md`, plans to
|
||||
`docs/plans/<iteration>.md`.
|
||||
Day-to-day discipline lives in the `~/dev/skills/` plugin —
|
||||
generic SKILL.md files at `~/dev/skills/<name>/SKILL.md`,
|
||||
agents under `~/dev/skills/<name>/agents/<agent>.md`. The
|
||||
plugin reads project-specific slots (paths, commands,
|
||||
vocabulary, naming, issue tracker, pipeline customisations)
|
||||
from this project's profile at
|
||||
`.claude/dev-cycle-profile.yml`. See `~/dev/skills/README.md`
|
||||
for the skill table and `~/dev/skills/docs/profile-schema.md`
|
||||
for the slot schema. Skills are sharper tools, not a
|
||||
replacement for orchestrator judgement.
|
||||
|
||||
Autonomous orchestrator mode — picking the next iter from the
|
||||
Gitea issue backlog and looping until done-state — is gated to the
|
||||
user-invoked `/boss` skill (`skills/boss/SKILL.md`). Outside
|
||||
`/boss`, the default is interactive collaboration: the user asks,
|
||||
Claude responds, Claude stops.
|
||||
Specs go to `docs/specs/<milestone>.md`, plans to
|
||||
`docs/plans/<iteration>.md` — both per `paths.spec_dir` /
|
||||
`paths.plan_dir` in the profile.
|
||||
|
||||
Autonomous orchestrator mode — picking the next iter from
|
||||
the Gitea issue backlog and looping until done-state — is
|
||||
gated to the user-invoked `/boss` skill
|
||||
(`~/dev/skills/boss/SKILL.md`). Outside `/boss`, the default
|
||||
is interactive collaboration: the user asks, Claude
|
||||
responds, Claude stops.
|
||||
|
||||
## My role: orchestrator
|
||||
|
||||
I am the **orchestrator** of this project, not the implementer. The
|
||||
agents under `skills/<name>/agents/` are my workers. I direct them,
|
||||
review their output, and integrate it. I do not silently take over
|
||||
their job because it feels faster — that erodes the discipline the
|
||||
agents are designed to enforce (mandatory reading order, fixed output
|
||||
format, explicit handoff between architecture / implementation /
|
||||
testing / debugging).
|
||||
agents under `~/dev/skills/<name>/agents/` are my workers. I direct
|
||||
them, review their output, and integrate it. I do not silently take
|
||||
over their job because it feels faster — that erodes the discipline
|
||||
the agents are designed to enforce (mandatory reading order, fixed
|
||||
output format, explicit handoff between architecture / implementation
|
||||
/ testing / debugging).
|
||||
|
||||
See @skills/README.md for the skill + agent roster.
|
||||
See `~/dev/skills/README.md` for the skill + agent roster.
|
||||
|
||||
### What this means in practice
|
||||
|
||||
@@ -115,9 +125,9 @@ See @skills/README.md for the skill + agent roster.
|
||||
invariants, commit bodies, and the contents of the `design/`
|
||||
ledger are my work product.
|
||||
- **Implement, refactor, write tests, diagnose bugs** — by default,
|
||||
delegated. `ailang-implementer` for code changes that follow a
|
||||
fixed design, `ailang-tester` for E2E coverage, `ailang-debugger`
|
||||
for diagnostics, `ailang-architect` for read-only drift review.
|
||||
delegated. `implementer` for code changes that follow a fixed
|
||||
design, `tester` for E2E coverage, `debugger` for diagnostics,
|
||||
`architect` for read-only drift review.
|
||||
- **Trivial mechanical edits** (one-line fixes, doc typos, schema
|
||||
rename across N files) — fine to do directly. Anything that
|
||||
requires reading large surface area or making judgement calls
|
||||
@@ -152,28 +162,36 @@ Two project-wide rules govern who touches git history and how:
|
||||
land on main, the remedy is a forward-fix commit, never a rewind.
|
||||
|
||||
These rules supersede earlier mechanics that involved per-iter
|
||||
branches and per-task agent commits. See `skills/README.md`
|
||||
"Conventions" for the same rules in skill-system form.
|
||||
branches and per-task agent commits. The same rules in plugin form
|
||||
live in `~/dev/skills/README.md` and
|
||||
`~/dev/skills/templates/CLAUDE.md.fragment`.
|
||||
|
||||
### Authority over `skills/` and the agent roster
|
||||
### Authority over the skill plugin
|
||||
|
||||
I am free to add, edit, retire, or replace skill or agent definitions
|
||||
whenever the orchestration needs it. Concretely:
|
||||
The skill plugin lives at `~/dev/skills/` and is shared across
|
||||
projects. I am free to add, edit, retire, or replace skill or
|
||||
agent definitions in the plugin whenever the orchestration
|
||||
needs it. Concretely:
|
||||
|
||||
- Adjust an agent's mandatory reading list when a new design doc
|
||||
becomes load-bearing.
|
||||
- Tighten an agent or skill output format if reports are getting
|
||||
verbose.
|
||||
- Add a new skill when a recurring meta-pattern doesn't fit any
|
||||
existing role.
|
||||
- Add a new agent when a recurring task doesn't fit any existing
|
||||
agent (e.g. a release-cutter).
|
||||
- Adjust an agent's mandatory reading list (in
|
||||
`~/dev/skills/<skill>/agents/<agent>.md`, or per-project via
|
||||
`standing_reading.by_role.<agent>` in this project's profile).
|
||||
- Tighten an agent or skill output format if reports are
|
||||
getting verbose.
|
||||
- Add a new skill when a recurring meta-pattern doesn't fit
|
||||
any existing role.
|
||||
- Add a new agent when a recurring task doesn't fit any
|
||||
existing agent (e.g. a release-cutter).
|
||||
- Retire an agent or skill that has become redundant.
|
||||
|
||||
Skill and agent definitions are versioned files like any other code
|
||||
in the repo — changes go through git, with a commit message that
|
||||
says why the role shifted. I treat them as part of the toolchain,
|
||||
not as immutable scripture.
|
||||
Plugin edits are universal (every project that consumes the
|
||||
plugin sees them). Edits that are only relevant to AILang go
|
||||
in the profile or in this CLAUDE.md, not in the plugin.
|
||||
|
||||
Skill and agent definitions are versioned files like any other
|
||||
code — changes go through git in `~/dev/skills/`, with a
|
||||
commit message that says why the role shifted. I treat them
|
||||
as part of the toolchain, not as immutable scripture.
|
||||
|
||||
### When NOT to delegate
|
||||
|
||||
@@ -214,25 +232,30 @@ naturally produces code that uses it AND whether the feature
|
||||
measurably improves correctness or removes redundancy. Aesthetic
|
||||
appeal does not count; neither does human ergonomics. Full criterion
|
||||
lives in `design/contracts/0004-feature-acceptance.md` and is
|
||||
applied as a gate by `skills/brainstorm/SKILL.md` during spec writing.
|
||||
applied as a gate by the plugin's `brainstorm` skill during spec
|
||||
writing — see `~/dev/skills/brainstorm/SKILL.md` Step 4.
|
||||
|
||||
## Bug fixes — TDD, always
|
||||
|
||||
Bug fixes are RED-first, autonomous, no orchestrator gate. See
|
||||
`skills/debug/SKILL.md` (trigger + handoff) and
|
||||
`skills/debug/agents/ailang-debugger.md` (Iron Law, four phases,
|
||||
`~/dev/skills/debug/SKILL.md` (trigger + handoff) and
|
||||
`~/dev/skills/debug/agents/debugger.md` (Iron Law, four phases,
|
||||
Phase 4.5 architecture trigger).
|
||||
|
||||
## Milestone cycle
|
||||
|
||||
Work clusters into **milestones**, each subdivided into
|
||||
**iterations**. Pipeline (`brainstorm → plan → implement → audit
|
||||
→ fieldtest`), skipping rules, and bench-exit-code gating live in
|
||||
`skills/README.md` and the per-skill `SKILL.md` files.
|
||||
**iterations**. Pipeline (`brainstorm → plan → implement →
|
||||
audit → fieldtest`), skipping rules, and exit-code gating
|
||||
live in `~/dev/skills/README.md` and the per-skill `SKILL.md`
|
||||
files; this project's pipeline configuration is in
|
||||
`.claude/dev-cycle-profile.yml` under `pipeline:`.
|
||||
|
||||
Vocabulary note: pre-2026-05-09 git history uses "iter" / "family";
|
||||
current vocabulary is "iteration" / "milestone". Old commits are
|
||||
not retroactively renamed.
|
||||
Vocabulary note: pre-2026-05-09 git history uses "iter" /
|
||||
"family"; current vocabulary is "iteration" / "milestone".
|
||||
Old commits are not retroactively renamed. The plugin uses
|
||||
"cycle" / "iteration" as generic vocabulary; this project's
|
||||
profile maps `cycle: milestone`.
|
||||
|
||||
## Roles of the `design/` ledger, `git log`, Gitea issues, `docs/specs/`, `docs/plans/`
|
||||
|
||||
@@ -245,8 +268,9 @@ not retroactively renamed.
|
||||
itself against the relevant contract before it can ship; if the
|
||||
feature requires changes to a contract, those changes are part of
|
||||
the same iteration. The `design/` ledger is also the artefact
|
||||
`ailang-architect` checks the code against during drift review.
|
||||
A contract describes only the actual present state; forward intent
|
||||
the `architect` agent checks the code against during drift
|
||||
review. A contract describes only the actual present state;
|
||||
forward intent
|
||||
goes to the Gitea backlog, history and rationale to `git log`
|
||||
(see `design/contracts/0007-honesty-rule.md`).
|
||||
|
||||
@@ -259,13 +283,31 @@ not retroactively renamed.
|
||||
`git log <prev-milestone-close>..HEAD --format=full`.
|
||||
|
||||
- **`docs/specs/<milestone>.md`** (since 2026-05-09): per-milestone
|
||||
design spec produced by `skills/brainstorm`. Hard-gate before any
|
||||
design spec produced by the `brainstorm` skill. Hard-gate before any
|
||||
plan or code work for the milestone.
|
||||
|
||||
- **`docs/plans/<iteration>.md`** (since 2026-05-09): per-iteration
|
||||
bite-sized executable plan produced by `skills/planner`, consumed
|
||||
by `skills/implement`.
|
||||
bite-sized executable plan produced by the `planner` skill, consumed
|
||||
by the `implement` skill.
|
||||
|
||||
Together these answer three questions: "what is the language right
|
||||
now?" (the `design/` ledger), "how did we get here?" (`git log`),
|
||||
and "what's next?" (Gitea backlog).
|
||||
|
||||
## Lockstep-invariant pairs
|
||||
|
||||
Two cross-file pairings must move together. A new arm in one
|
||||
without the matching update in the other ships silently broken.
|
||||
The `architect` agent walks these pairs during audit drift
|
||||
review, and `plan-recon` consults this section when computing
|
||||
the cross-references column of a file-map.
|
||||
|
||||
| Pair | Failure mode |
|
||||
|---|---|
|
||||
| `Pattern::Lit::*` typecheck rejects in `crates/ailang-check/src/lib.rs` ↔ pre-desugar walkers in `crates/ailang-check/src/pre_desugar_validation.rs` | A reject arm placed AFTER `desugar_module` in the call chain is unreachable through the public `check` API if the desugar pass rewrites that pattern shape first (e.g. `desugar::build_eq` rewrites `Pattern::Lit::Float` into `(== scrut lit)` before typecheck runs). New rejects on a `Pattern::Lit::*` shape MUST live in `pre_desugar_validation.rs`, or be paired with a written guarantee that no desugar pass eats the shape. |
|
||||
| `lower_app` arms in `crates/ailang-codegen/src/lib.rs::lower_app` (line ~1749) ↔ name recognition in `crates/ailang-codegen/src/lib.rs::is_static_callee` (line ~2189) | A name lowered by a direct `lower_app` arm but unrecognised by `is_static_callee` falls through to the indirect-call path with `UnknownVar` (`UnknownVar` panic in worst case). Every new builtin lowering arm in `lower_app` must have a matching `is_static_callee` entry. |
|
||||
|
||||
Walk procedure: for each milestone-scope commit-range arm
|
||||
landed in these files (use `git diff <prev-close>..HEAD --` on
|
||||
each file in the pair), open both files in the pair and confirm
|
||||
the matching update is present. Flag any unpaired arm as drift.
|
||||
|
||||
Reference in New Issue
Block a user