From 18c73f38959b3f1774623c5971e86efee2d71142 Mon Sep 17 00:00:00 2001 From: kernel-public-sync Date: Mon, 20 Jul 2026 14:26:12 +0000 Subject: [PATCH] chore: sync public export --- .github/copilot-instructions.md | 14 +++ .github/instructions/review.instructions.md | 15 +++ .github/instructions/testing.instructions.md | 13 +++ .github/skills/accessibility-scout/SKILL.md | 47 ++++++++ .github/skills/adapter-compiler/SKILL.md | 47 ++++++++ .github/skills/adr-capture/SKILL.md | 48 +++++++++ .github/skills/agent-scheduler/SKILL.md | 47 ++++++++ .github/skills/api-contract-guardian/SKILL.md | 47 ++++++++ .github/skills/context-router/SKILL.md | 48 +++++++++ .github/skills/debug-probe/SKILL.md | 48 +++++++++ .github/skills/dependency-sentinel/SKILL.md | 47 ++++++++ .github/skills/design-critic/SKILL.md | 48 +++++++++ .github/skills/diff-surgeon/SKILL.md | 48 +++++++++ .github/skills/docs-sync/SKILL.md | 46 ++++++++ .github/skills/evidence-ledger/SKILL.md | 48 +++++++++ .github/skills/handoff-packet/SKILL.md | 48 +++++++++ .github/skills/invariant-harvester/SKILL.md | 48 +++++++++ .github/skills/kernel-core/SKILL.md | 48 +++++++++ .github/skills/memory-gc/SKILL.md | 46 ++++++++ .github/skills/mistake-miner/SKILL.md | 46 ++++++++ .github/skills/perf-budget/SKILL.md | 46 ++++++++ .github/skills/policy-gate/SKILL.md | 46 ++++++++ .github/skills/pr-narrator/SKILL.md | 47 ++++++++ .github/skills/prompt-to-skill/SKILL.md | 48 +++++++++ .github/skills/release-captain/SKILL.md | 47 ++++++++ .github/skills/repo-cartographer/SKILL.md | 49 +++++++++ .github/skills/reproducer-forge/SKILL.md | 47 ++++++++ .github/skills/review-bot-judge/SKILL.md | 46 ++++++++ .github/skills/risk-map/SKILL.md | 47 ++++++++ .github/skills/security-tripwire/SKILL.md | 46 ++++++++ .github/skills/skill-evaluator/SKILL.md | 47 ++++++++ .../skills/stale-context-detector/SKILL.md | 47 ++++++++ .github/skills/task-contract/SKILL.md | 48 +++++++++ .../skills/team-conventions-miner/SKILL.md | 47 ++++++++ .github/skills/test-scout/SKILL.md | 47 ++++++++ .github/skills/trigger-linter/SKILL.md | 47 ++++++++ .github/skills/ui-verifier/SKILL.md | 46 ++++++++ .github/skills/verify-lattice/SKILL.md | 48 +++++++++ .github/skills/worktree-orchestrator/SKILL.md | 47 ++++++++ CHANGELOG.md | 25 +++++ README.md | 102 +++++++----------- RELEASE.md | 35 +++--- docs/kernel-in-5-minutes.md | 64 +++++++++++ package.json | 18 +++- src/adapters/canonical-skills.ts | 74 ++++++++++++- src/adapters/claude.ts | 2 +- src/adapters/codex.ts | 15 +-- src/adapters/common.ts | 2 +- src/adapters/cursor.ts | 59 ++++++++-- src/adapters/gemini.ts | 2 +- src/adapters/github-copilot.ts | 30 ++---- src/adapters/junie.ts | 2 +- src/adapters/kiro.ts | 7 +- src/cli/index.ts | 4 +- src/core/eval.ts | 66 +++++++++++- src/core/init.ts | 2 +- src/core/skill-generator.ts | 33 ++++-- src/core/skills.ts | 83 +++++++++++++- tests/adapter-compiler.test.ts | 2 +- .../.agent/skills/evidence-ledger/SKILL.md | 28 +++-- .../.agent/skills/kernel-core/SKILL.md | 13 +++ .../.agent/skills/evidence-ledger/SKILL.md | 28 +++-- .../.agent/skills/kernel-core/SKILL.md | 13 +++ .../03-skills/adapter-compiler.md | 39 ++++--- .../03-skills/evidence-ledger.md | 43 +++++--- .../03-skills/handoff-packet.md | 39 ++++--- .../03-skills/kernel-core.md | 42 +++++--- .../03-skills/task-contract.md | 41 ++++--- .../03-skills/verify-lattice.md | 41 ++++--- .../.agent/skills/kernel-core/SKILL.md | 13 +++ tests/priority-adapters.test.ts | 22 +++- tests/skill-generator.test.ts | 5 +- tests/validate.test.ts | 3 +- 73 files changed, 2496 insertions(+), 241 deletions(-) create mode 100644 .github/copilot-instructions.md create mode 100644 .github/instructions/review.instructions.md create mode 100644 .github/instructions/testing.instructions.md create mode 100644 .github/skills/accessibility-scout/SKILL.md create mode 100644 .github/skills/adapter-compiler/SKILL.md create mode 100644 .github/skills/adr-capture/SKILL.md create mode 100644 .github/skills/agent-scheduler/SKILL.md create mode 100644 .github/skills/api-contract-guardian/SKILL.md create mode 100644 .github/skills/context-router/SKILL.md create mode 100644 .github/skills/debug-probe/SKILL.md create mode 100644 .github/skills/dependency-sentinel/SKILL.md create mode 100644 .github/skills/design-critic/SKILL.md create mode 100644 .github/skills/diff-surgeon/SKILL.md create mode 100644 .github/skills/docs-sync/SKILL.md create mode 100644 .github/skills/evidence-ledger/SKILL.md create mode 100644 .github/skills/handoff-packet/SKILL.md create mode 100644 .github/skills/invariant-harvester/SKILL.md create mode 100644 .github/skills/kernel-core/SKILL.md create mode 100644 .github/skills/memory-gc/SKILL.md create mode 100644 .github/skills/mistake-miner/SKILL.md create mode 100644 .github/skills/perf-budget/SKILL.md create mode 100644 .github/skills/policy-gate/SKILL.md create mode 100644 .github/skills/pr-narrator/SKILL.md create mode 100644 .github/skills/prompt-to-skill/SKILL.md create mode 100644 .github/skills/release-captain/SKILL.md create mode 100644 .github/skills/repo-cartographer/SKILL.md create mode 100644 .github/skills/reproducer-forge/SKILL.md create mode 100644 .github/skills/review-bot-judge/SKILL.md create mode 100644 .github/skills/risk-map/SKILL.md create mode 100644 .github/skills/security-tripwire/SKILL.md create mode 100644 .github/skills/skill-evaluator/SKILL.md create mode 100644 .github/skills/stale-context-detector/SKILL.md create mode 100644 .github/skills/task-contract/SKILL.md create mode 100644 .github/skills/team-conventions-miner/SKILL.md create mode 100644 .github/skills/test-scout/SKILL.md create mode 100644 .github/skills/trigger-linter/SKILL.md create mode 100644 .github/skills/ui-verifier/SKILL.md create mode 100644 .github/skills/verify-lattice/SKILL.md create mode 100644 .github/skills/worktree-orchestrator/SKILL.md create mode 100644 docs/kernel-in-5-minutes.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..4db9d79 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,14 @@ + + +# GitHub Copilot Instructions + +This repository uses **Kernel** for repo-local agent quality artifacts. + +Project: kernel-skills + +Before non-trivial changes, inspect `.agent/kernel.yaml` and `.agent/state/current-task.md`. +Record verification in `.agent/evidence/` before claiming completion. + + + + diff --git a/.github/instructions/review.instructions.md b/.github/instructions/review.instructions.md new file mode 100644 index 0000000..99667da --- /dev/null +++ b/.github/instructions/review.instructions.md @@ -0,0 +1,15 @@ + + +# Kernel Review Instructions + +Review agent changes in kernel-skills against Kernel artifacts. + +Prime directive: No contract, no implementation. No evidence, no completion. No handoff, no continuity. + +- Confirm the task contract matches the diff. +- Confirm verification evidence supports completion claims. +- Focus on high-risk paths, generated outputs, and missing tests. + + + + diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md new file mode 100644 index 0000000..484906f --- /dev/null +++ b/.github/instructions/testing.instructions.md @@ -0,0 +1,13 @@ + + +# Kernel Testing Instructions + +Use Kernel verification evidence for kernel-skills. + +- Prefer targeted tests for local behavior changes. +- Run project-level checks for refactors and broad changes. +- Record skipped checks and remaining risks in `.agent/evidence/`. + + + + diff --git a/.github/skills/accessibility-scout/SKILL.md b/.github/skills/accessibility-scout/SKILL.md new file mode 100644 index 0000000..d6b2ade --- /dev/null +++ b/.github/skills/accessibility-scout/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: accessibility-scout +description: "Use for UI changes. Reviews keyboard, focus, semantic HTML, labels, contrast, and ARIA. Do not trigger it for unrelated work just because the skill exists." +--- +# accessibility-scout + +## Purpose + +Use for UI changes. Reviews keyboard, focus, semantic HTML, labels, contrast, and ARIA. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Check keyboard path. +2. Check focus states. +3. Check labels. +4. Avoid ARIA misuse. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/adapter-compiler/SKILL.md b/.github/skills/adapter-compiler/SKILL.md new file mode 100644 index 0000000..71227bd --- /dev/null +++ b/.github/skills/adapter-compiler/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: adapter-compiler +description: "Use when generating ADE-specific files from canonical Kernel source. Do not trigger it for unrelated work just because the skill exists." +--- +# adapter-compiler + +## Purpose + +Use when generating ADE-specific files from canonical Kernel source. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Read `.agent/kernel.yaml`. +2. Generate adapter outputs. +3. Preserve manual sections. +4. Validate freshness. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/adr-capture/SKILL.md b/.github/skills/adr-capture/SKILL.md new file mode 100644 index 0000000..8f7a88c --- /dev/null +++ b/.github/skills/adr-capture/SKILL.md @@ -0,0 +1,48 @@ + + +--- +name: adr-capture +description: "Use when an architectural decision or durable tradeoff is made. Do not trigger it for unrelated work just because the skill exists." +--- +# adr-capture + +## Purpose + +Use when an architectural decision or durable tradeoff is made. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Record context. +2. Record decision. +3. Record alternatives. +4. Record consequences. +5. Record follow-up. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/agent-scheduler/SKILL.md b/.github/skills/agent-scheduler/SKILL.md new file mode 100644 index 0000000..fa47b00 --- /dev/null +++ b/.github/skills/agent-scheduler/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: agent-scheduler +description: "Use when a plan has multiple tasks. Decides serial vs parallel execution. Do not trigger it for unrelated work just because the skill exists." +--- +# agent-scheduler + +## Purpose + +Use when a plan has multiple tasks. Decides serial vs parallel execution. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Classify dependencies. +2. Identify path collisions. +3. Split safe tasks. +4. Sequence risky tasks. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/api-contract-guardian/SKILL.md b/.github/skills/api-contract-guardian/SKILL.md new file mode 100644 index 0000000..f66fbc7 --- /dev/null +++ b/.github/skills/api-contract-guardian/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: api-contract-guardian +description: "Use when changing APIs, SDKs, CLIs, config, schemas, events, migrations, or public types. Do not trigger it for unrelated work just because the skill exists." +--- +# api-contract-guardian + +## Purpose + +Use when changing APIs, SDKs, CLIs, config, schemas, events, migrations, or public types. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Detect public contract changes. +2. Check backward compatibility. +3. Require docs/changelog updates. +4. Require contract tests. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/context-router/SKILL.md b/.github/skills/context-router/SKILL.md new file mode 100644 index 0000000..8e2d8ed --- /dev/null +++ b/.github/skills/context-router/SKILL.md @@ -0,0 +1,48 @@ + + +--- +name: context-router +description: "Use before planning or coding. Builds a curated context bundle from repo maps, changed files, tests, docs, imports, and task contract. Do not trigger it for unrelated work just because the skill exists." +--- +# context-router + +## Purpose + +Use before planning or coding. Builds a curated context bundle from repo maps, changed files, tests, docs, imports, and task contract. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Identify relevant files. +2. Identify relevant tests and commands. +3. Identify docs and constraints. +4. Explicitly exclude likely irrelevant context. +5. Record bundle in `.agent/state/context-bundle.md`. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/debug-probe/SKILL.md b/.github/skills/debug-probe/SKILL.md new file mode 100644 index 0000000..0205c9f --- /dev/null +++ b/.github/skills/debug-probe/SKILL.md @@ -0,0 +1,48 @@ + + +--- +name: debug-probe +description: "Use for bugs, flaky tests, incidents, failing commands, or unclear behavior. Establishes causality before fixes. Do not trigger it for unrelated work just because the skill exists." +--- +# debug-probe + +## Purpose + +Use for bugs, flaky tests, incidents, failing commands, or unclear behavior. Establishes causality before fixes. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Reproduce symptom. +2. Create causal graph. +3. Localize boundary. +4. Add probe. +5. Avoid fixes before evidence. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/dependency-sentinel/SKILL.md b/.github/skills/dependency-sentinel/SKILL.md new file mode 100644 index 0000000..022245c --- /dev/null +++ b/.github/skills/dependency-sentinel/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: dependency-sentinel +description: "Use when manifests or lockfiles change. Analyzes dependency upgrade risk. Do not trigger it for unrelated work just because the skill exists." +--- +# dependency-sentinel + +## Purpose + +Use when manifests or lockfiles change. Analyzes dependency upgrade risk. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Classify direct/transitive. +2. Assess semver risk. +3. Identify affected imports. +4. Recommend verification. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/design-critic/SKILL.md b/.github/skills/design-critic/SKILL.md new file mode 100644 index 0000000..12757d9 --- /dev/null +++ b/.github/skills/design-critic/SKILL.md @@ -0,0 +1,48 @@ + + +--- +name: design-critic +description: "Use after a proposed plan and before implementation. Performs adversarial review of assumptions, complexity, failure modes, and simpler alternatives. Do not trigger it for unrelated work just because the skill exists." +--- +# design-critic + +## Purpose + +Use after a proposed plan and before implementation. Performs adversarial review of assumptions, complexity, failure modes, and simpler alternatives. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Attack assumptions. +2. Find missing edge cases. +3. Suggest simpler design. +4. Identify rollback concerns. +5. Approve, revise, or reject plan. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/diff-surgeon/SKILL.md b/.github/skills/diff-surgeon/SKILL.md new file mode 100644 index 0000000..4a5f9d4 --- /dev/null +++ b/.github/skills/diff-surgeon/SKILL.md @@ -0,0 +1,48 @@ + + +--- +name: diff-surgeon +description: "Use after code changes for surgical fixes, hotfixes, and high-risk work. Enforces minimal, relevant diffs. Do not trigger it for unrelated work just because the skill exists." +--- +# diff-surgeon + +## Purpose + +Use after code changes for surgical fixes, hotfixes, and high-risk work. Enforces minimal, relevant diffs. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Find unrelated changes. +2. Find broad rewrites. +3. Check public behavior changes. +4. Suggest smaller patch. +5. Record diff surgery report. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/docs-sync/SKILL.md b/.github/skills/docs-sync/SKILL.md new file mode 100644 index 0000000..81e36d3 --- /dev/null +++ b/.github/skills/docs-sync/SKILL.md @@ -0,0 +1,46 @@ + + +--- +name: docs-sync +description: "Use after behavior, API, config, command, or user-facing changes. Do not trigger it for unrelated work just because the skill exists." +--- +# docs-sync + +## Purpose + +Use after behavior, API, config, command, or user-facing changes. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Find docs likely affected. +2. Suggest updates. +3. Record docs intentionally unchanged. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/evidence-ledger/SKILL.md b/.github/skills/evidence-ledger/SKILL.md new file mode 100644 index 0000000..7b1a4db --- /dev/null +++ b/.github/skills/evidence-ledger/SKILL.md @@ -0,0 +1,48 @@ + + +--- +name: evidence-ledger +description: "Use after implementation, debugging, review, or release. Records claims and proof. Do not trigger it for unrelated work just because the skill exists." +--- +# evidence-ledger + +## Purpose + +Use after implementation, debugging, review, or release. Records claims and proof. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Record commands. +2. Record exit codes. +3. Record tests and screenshots. +4. Record failures before fixes when applicable. +5. Record remaining risks. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/handoff-packet/SKILL.md b/.github/skills/handoff-packet/SKILL.md new file mode 100644 index 0000000..fc057f7 --- /dev/null +++ b/.github/skills/handoff-packet/SKILL.md @@ -0,0 +1,48 @@ + + +--- +name: handoff-packet +description: "Use when switching ADEs, ending a long session, pausing incomplete work, or before another agent continues. Do not trigger it for unrelated work just because the skill exists." +--- +# handoff-packet + +## Purpose + +Use when switching ADEs, ending a long session, pausing incomplete work, or before another agent continues. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Summarize task. +2. List changed files. +3. List commands run. +4. List known failures. +5. List next actions and do-not-repeat notes. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/invariant-harvester/SKILL.md b/.github/skills/invariant-harvester/SKILL.md new file mode 100644 index 0000000..9618738 --- /dev/null +++ b/.github/skills/invariant-harvester/SKILL.md @@ -0,0 +1,48 @@ + + +--- +name: invariant-harvester +description: "Use before refactors, migrations, bug fixes, and public contract changes. Extracts behavior that must remain true. Do not trigger it for unrelated work just because the skill exists." +--- +# invariant-harvester + +## Purpose + +Use before refactors, migrations, bug fixes, and public contract changes. Extracts behavior that must remain true. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Inspect tests/docs/types. +2. List public contracts. +3. List tacit behavior. +4. Mark invariants as hard or soft. +5. Link invariants to verification. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/kernel-core/SKILL.md b/.github/skills/kernel-core/SKILL.md new file mode 100644 index 0000000..0cd0119 --- /dev/null +++ b/.github/skills/kernel-core/SKILL.md @@ -0,0 +1,48 @@ + + +--- +name: kernel-core +description: "Use before and after any non-trivial coding-agent task. Creates or updates a task contract, identifies relevant context, selects quality gates, requires evidence before completion, and writes a handoff packet when needed. Do not use for trivial one-line edits unless the touched area is high-risk." +--- +# kernel-core + +## Purpose + +Use before and after any non-trivial coding-agent task. Creates or updates a task contract, identifies relevant context, selects quality gates, requires evidence before completion, and writes a handoff packet when needed. Do not use for trivial one-line edits unless the touched area is high-risk. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Read or create `.agent/state/current-task.md`. +2. Classify task type and risk. +3. Route to relevant subskills. +4. Require evidence before completion. +5. Create handoff if context is long or work is incomplete. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/memory-gc/SKILL.md b/.github/skills/memory-gc/SKILL.md new file mode 100644 index 0000000..86851f2 --- /dev/null +++ b/.github/skills/memory-gc/SKILL.md @@ -0,0 +1,46 @@ + + +--- +name: memory-gc +description: "Use when agent instruction files or rules become bloated. Do not trigger it for unrelated work just because the skill exists." +--- +# memory-gc + +## Purpose + +Use when agent instruction files or rules become bloated. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Find duplicates. +2. Remove obsolete guidance. +3. Keep commands, constraints, verification, conventions. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/mistake-miner/SKILL.md b/.github/skills/mistake-miner/SKILL.md new file mode 100644 index 0000000..651e8e5 --- /dev/null +++ b/.github/skills/mistake-miner/SKILL.md @@ -0,0 +1,46 @@ + + +--- +name: mistake-miner +description: "Use after agent failure, bad review, reverted PR, repeated mistake, or process miss. Do not trigger it for unrelated work just because the skill exists." +--- +# mistake-miner + +## Purpose + +Use after agent failure, bad review, reverted PR, repeated mistake, or process miss. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Classify root process failure. +2. Propose rule/invariant/test/skill update. +3. Avoid adding vague rules. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/perf-budget/SKILL.md b/.github/skills/perf-budget/SKILL.md new file mode 100644 index 0000000..21d6621 --- /dev/null +++ b/.github/skills/perf-budget/SKILL.md @@ -0,0 +1,46 @@ + + +--- +name: perf-budget +description: "Use for hot paths, query changes, rendering, caching, bundle size, or loops. Do not trigger it for unrelated work just because the skill exists." +--- +# perf-budget + +## Purpose + +Use for hot paths, query changes, rendering, caching, bundle size, or loops. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Define budget. +2. Measure or reason explicitly. +3. Flag regressions. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/policy-gate/SKILL.md b/.github/skills/policy-gate/SKILL.md new file mode 100644 index 0000000..7acf37c --- /dev/null +++ b/.github/skills/policy-gate/SKILL.md @@ -0,0 +1,46 @@ + + +--- +name: policy-gate +description: "Use before destructive commands, dependency updates, migrations, deployment commands, force pushes, or critical path edits. Do not trigger it for unrelated work just because the skill exists." +--- +# policy-gate + +## Purpose + +Use before destructive commands, dependency updates, migrations, deployment commands, force pushes, or critical path edits. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Classify operation as safe/review/block. +2. Check path and command policy with `kernel policy check`. +3. Require explicit approval for review/block classes. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/pr-narrator/SKILL.md b/.github/skills/pr-narrator/SKILL.md new file mode 100644 index 0000000..2ecb480 --- /dev/null +++ b/.github/skills/pr-narrator/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: pr-narrator +description: "Use before opening or updating a PR. Produces reviewer-optimized summary, risk, verification, and rollback notes. Do not trigger it for unrelated work just because the skill exists." +--- +# pr-narrator + +## Purpose + +Use before opening or updating a PR. Produces reviewer-optimized summary, risk, verification, and rollback notes. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Summarize why and what changed. +2. List verification evidence. +3. Identify reviewer focus. +4. Include rollback plan. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/prompt-to-skill/SKILL.md b/.github/skills/prompt-to-skill/SKILL.md new file mode 100644 index 0000000..fa340ad --- /dev/null +++ b/.github/skills/prompt-to-skill/SKILL.md @@ -0,0 +1,48 @@ + + +--- +name: prompt-to-skill +description: "Use when a repeated prompt should become a reusable skill. Do not trigger it for unrelated work just because the skill exists." +--- +# prompt-to-skill + +## Purpose + +Use when a repeated prompt should become a reusable skill. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Extract trigger. +2. Define workflow. +3. Define output artifact. +4. Add tests. +5. Compile adapters. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/release-captain/SKILL.md b/.github/skills/release-captain/SKILL.md new file mode 100644 index 0000000..8cbb2c0 --- /dev/null +++ b/.github/skills/release-captain/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: release-captain +description: "Use for release prep, rollout, migration, or post-merge shipping. Do not trigger it for unrelated work just because the skill exists." +--- +# release-captain + +## Purpose + +Use for release prep, rollout, migration, or post-merge shipping. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Draft changelog. +2. Define rollout. +3. Define rollback. +4. Define post-release checks. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/repo-cartographer/SKILL.md b/.github/skills/repo-cartographer/SKILL.md new file mode 100644 index 0000000..e8b6618 --- /dev/null +++ b/.github/skills/repo-cartographer/SKILL.md @@ -0,0 +1,49 @@ + + +--- +name: repo-cartographer +description: "Use when initializing, onboarding, or exploring architecture, or during major refactors. Creates maps of repo topology, commands, entrypoints, tests, packages, and critical flows. Do not trigger it for unrelated work just because the skill exists." +--- +# repo-cartographer + +## Purpose + +Use when initializing, onboarding, or exploring architecture, or during major refactors. Creates maps of repo topology, commands, entrypoints, tests, packages, and critical flows. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Detect package manager and monorepo workspaces. +2. Map commands from package scripts, Makefile/justfile, and `kernel.yaml`. +3. Map entrypoints from root `package.json`. +4. Map test locations, frameworks, and config files. +5. Map subsystem boundaries and workspace packages. +6. Write `.agent/maps/repo.json` (version 2). + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/reproducer-forge/SKILL.md b/.github/skills/reproducer-forge/SKILL.md new file mode 100644 index 0000000..b63265a --- /dev/null +++ b/.github/skills/reproducer-forge/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: reproducer-forge +description: "Use for bug reports and flaky failures. Creates minimal reproducible cases. Do not trigger it for unrelated work just because the skill exists." +--- +# reproducer-forge + +## Purpose + +Use for bug reports and flaky failures. Creates minimal reproducible cases. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Minimize input. +2. Capture command/env/seed. +3. Create failing test where practical. +4. Document expected vs actual. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/review-bot-judge/SKILL.md b/.github/skills/review-bot-judge/SKILL.md new file mode 100644 index 0000000..4b5dcc0 --- /dev/null +++ b/.github/skills/review-bot-judge/SKILL.md @@ -0,0 +1,46 @@ + + +--- +name: review-bot-judge +description: "Use for pre-merge review. Reviews code against task contract, invariants, risks, and evidence. Do not trigger it for unrelated work just because the skill exists." +--- +# review-bot-judge + +## Purpose + +Use for pre-merge review. Reviews code against task contract, invariants, risks, and evidence. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Classify findings P0/P1/P2/nit. +2. Check correctness, security, performance, compatibility, tests, minimality. +3. Call out false-positive risk. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/risk-map/SKILL.md b/.github/skills/risk-map/SKILL.md new file mode 100644 index 0000000..123c542 --- /dev/null +++ b/.github/skills/risk-map/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: risk-map +description: "Use before editing high-impact code. Maps files and subsystems to blast radius and verification requirements. Do not trigger it for unrelated work just because the skill exists." +--- +# risk-map + +## Purpose + +Use before editing high-impact code. Maps files and subsystems to blast radius and verification requirements. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Identify high-risk paths from `.agent/maps/risk.json`. +2. Identify required checks. +3. Detect ownership from `risk.json` `ownership` entries (CODEOWNERS + config). +4. Escalate verification. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/security-tripwire/SKILL.md b/.github/skills/security-tripwire/SKILL.md new file mode 100644 index 0000000..a6f8eb5 --- /dev/null +++ b/.github/skills/security-tripwire/SKILL.md @@ -0,0 +1,46 @@ + + +--- +name: security-tripwire +description: "Use when touching auth, crypto, secrets, SQL, shell execution, file uploads, permissions, deserialization, webhooks, SSRF, or tenancy. Do not trigger it for unrelated work just because the skill exists." +--- +# security-tripwire + +## Purpose + +Use when touching auth, crypto, secrets, SQL, shell execution, file uploads, permissions, deserialization, webhooks, SSRF, or tenancy. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Apply targeted security checklist. +2. Identify vulnerability class. +3. Require security-specific verification. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/skill-evaluator/SKILL.md b/.github/skills/skill-evaluator/SKILL.md new file mode 100644 index 0000000..fb92415 --- /dev/null +++ b/.github/skills/skill-evaluator/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: skill-evaluator +description: "Use before releasing skill changes. Regression-tests skill triggers and outputs. Do not trigger it for unrelated work just because the skill exists." +--- +# skill-evaluator + +## Purpose + +Use before releasing skill changes. Regression-tests skill triggers and outputs. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Run prompt fixtures. +2. Check activation behavior. +3. Check output format. +4. Prevent regressions. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/stale-context-detector/SKILL.md b/.github/skills/stale-context-detector/SKILL.md new file mode 100644 index 0000000..cfca19d --- /dev/null +++ b/.github/skills/stale-context-detector/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: stale-context-detector +description: "Use after rebases, long sessions, branch changes, failing commands, or generated maps older than source. Do not trigger it for unrelated work just because the skill exists." +--- +# stale-context-detector + +## Purpose + +Use after rebases, long sessions, branch changes, failing commands, or generated maps older than source. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Check files changed since read. +2. Check branch state. +3. Check map age. +4. Require reread when stale. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/task-contract/SKILL.md b/.github/skills/task-contract/SKILL.md new file mode 100644 index 0000000..98923ca --- /dev/null +++ b/.github/skills/task-contract/SKILL.md @@ -0,0 +1,48 @@ + + +--- +name: task-contract +description: "Use before non-trivial coding, debugging, refactoring, migration, or review work. Converts vague requests into compact goals, non-goals, assumptions, risks, verification, and done criteria. Do not trigger it for unrelated work just because the skill exists." +--- +# task-contract + +## Purpose + +Use before non-trivial coding, debugging, refactoring, migration, or review work. Converts vague requests into compact goals, non-goals, assumptions, risks, verification, and done criteria. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Define task type. +2. Write observable goal. +3. Write non-goals. +4. List assumptions as confirmed or unconfirmed. +5. Define verification and done criteria. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/team-conventions-miner/SKILL.md b/.github/skills/team-conventions-miner/SKILL.md new file mode 100644 index 0000000..9181d3b --- /dev/null +++ b/.github/skills/team-conventions-miner/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: team-conventions-miner +description: "Use when onboarding or when repeated style mistakes appear. Infers conventions from code and history. Do not trigger it for unrelated work just because the skill exists." +--- +# team-conventions-miner + +## Purpose + +Use when onboarding or when repeated style mistakes appear. Infers conventions from code and history. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Sample code. +2. Infer style. +3. Assign confidence. +4. Propose durable rules. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/test-scout/SKILL.md b/.github/skills/test-scout/SKILL.md new file mode 100644 index 0000000..6882fea --- /dev/null +++ b/.github/skills/test-scout/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: test-scout +description: "Use before writing or running tests. Finds the cheapest meaningful verification surface. Do not trigger it for unrelated work just because the skill exists." +--- +# test-scout + +## Purpose + +Use before writing or running tests. Finds the cheapest meaningful verification surface. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Locate nearest tests. +2. Rank tests by relevance and cost. +3. Recommend targeted test path. +4. Identify missing regression test. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/trigger-linter/SKILL.md b/.github/skills/trigger-linter/SKILL.md new file mode 100644 index 0000000..111c2f8 --- /dev/null +++ b/.github/skills/trigger-linter/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: trigger-linter +description: "Use when writing or updating skills. Prevents vague or overbroad activation descriptions. Do not trigger it for unrelated work just because the skill exists." +--- +# trigger-linter + +## Purpose + +Use when writing or updating skills. Prevents vague or overbroad activation descriptions. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Check description specificity. +2. Find overlap. +3. Require do-not-use conditions. +4. Require measurable outputs. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/ui-verifier/SKILL.md b/.github/skills/ui-verifier/SKILL.md new file mode 100644 index 0000000..5e5068e --- /dev/null +++ b/.github/skills/ui-verifier/SKILL.md @@ -0,0 +1,46 @@ + + +--- +name: ui-verifier +description: "Use for UI, CSS, layout, component, or frontend behavior changes. Do not trigger it for unrelated work just because the skill exists." +--- +# ui-verifier + +## Purpose + +Use for UI, CSS, layout, component, or frontend behavior changes. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Require visual check. +2. Check states and responsive behavior. +3. Record screenshots when available. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/verify-lattice/SKILL.md b/.github/skills/verify-lattice/SKILL.md new file mode 100644 index 0000000..6219248 --- /dev/null +++ b/.github/skills/verify-lattice/SKILL.md @@ -0,0 +1,48 @@ + + +--- +name: verify-lattice +description: "Use before declaring completion. Selects and records the appropriate verification level for the task. Do not trigger it for unrelated work just because the skill exists." +--- +# verify-lattice + +## Purpose + +Use before declaring completion. Selects and records the appropriate verification level for the task. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Choose L0-L5 verification. +2. Run or request commands. +3. Record outputs. +4. Mark completion status. +5. List remaining risk. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/.github/skills/worktree-orchestrator/SKILL.md b/.github/skills/worktree-orchestrator/SKILL.md new file mode 100644 index 0000000..6ef4f9b --- /dev/null +++ b/.github/skills/worktree-orchestrator/SKILL.md @@ -0,0 +1,47 @@ + + +--- +name: worktree-orchestrator +description: "Use when parallel agent work or isolated branches are needed. Do not trigger it for unrelated work just because the skill exists." +--- +# worktree-orchestrator + +## Purpose + +Use when parallel agent work or isolated branches are needed. + +## Trigger + +Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. + +## Workflow + +1. Create worktree plan. +2. Lock paths. +3. Name branch. +4. Prevent collisions. + +## Output + +Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. + +## Quality bar + +- Be specific. +- Prefer observable facts over impressions. +- Record uncertainty explicitly. +- Avoid bloating global instruction files. +- Link output to the current task contract when applicable. + +## Related skills + +- [[kernel-core]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] + +## Manual notes + + + + diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f50b5e..b7e8108 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,31 @@ All notable changes to Kernel will be documented in this file. This project follows semantic versioning once public releases begin. +## 0.3.0 + +### Added + +- Market positioning: "A paper trail for AI coding agents" / "AGENTS.md, but with a memory." +- Core skill pack quality: worked examples for the six MVP skills, unique related links, artifact-shape eval fixtures. +- Skill generator prefers concrete Trigger/Purpose text; Core docs require `## Example`. +- Skill lint gates for Core: missing Example, self-related links, generic Related skills boilerplate. +- Cursor adapter: rule YAML frontmatter (`alwaysApply` / `description`), `.cursor/skills/`, shared `.agents/skills/`. +- Kiro adapter: `.kiro/skills/` plus shared `.agents/skills/`. +- GitHub Copilot adapter also emits shared `.agents/skills/`. +- Five-minute onboarding doc: `docs/kernel-in-5-minutes.md`. +- npm package `keywords` for discoverability. + +### Changed + +- README quickstart defaults to Core (`mvp`), not `lint-ready`. +- Product Brief collapses naming to Kernel + `kernel` CLI; drops invented category jargon from public pitch. +- Adapter Matrix documents shared Agent Skills path and Cursor/Kiro skill outputs. + +### Notes + +- Package metadata is publishable (`private` removed). Publish `@mattbaconz/kernel@0.3.0` from public `mattbaconz/kernel` via `npm-release.yml` after sync. +- Public source of truth for npm remains `mattbaconz/kernel`. + ## 0.2.0 ### Added diff --git a/README.md b/README.md index 7e405ec..4ed4335 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,69 @@ # Kernel -Kernel is a repo-local quality system and portable operating layer for coding agents. +**A paper trail for AI coding agents.** -It helps Codex, Claude Code, Cursor, Kiro, GitHub Copilot, Gemini CLI, Windsurf, OpenCode, Junie, Zed, and future ADEs work from the same durable task contracts, repo maps, verification evidence, policies, handoff packets, canonical skills, and generated adapter files. +Kernel is AGENTS.md with a memory: git-committed task contracts, verification evidence, and handoff notes that survive between sessions and tools — plus a Core skill pack every major coding agent can read. -## Status - -Kernel is pre-release software. The source repository is public, and the package identity is `@mattbaconz/kernel`. The package is still private and unpublished until an explicit public release task. - -## What Kernel Provides - -- `kernel init` for `.agent/` bootstrap -- task contracts under `.agent/state/` and `.agent/contracts/` -- evidence ledgers under `.agent/evidence/` -- handoff packets under `.agent/handoffs/` -- deterministic repo maps under `.agent/maps/` -- canonical skill generation under `.agent/skills/` -- adapter compilation for Codex, Claude Code, Cursor, Kiro, and GitHub Copilot -- validation, skill linting, static skill eval fixtures, and JSON schema discovery +It works with Codex, Claude Code, Cursor, Kiro, GitHub Copilot, Gemini CLI, Windsurf, OpenCode, Junie, Zed, and future ADEs from one repo-local source of truth under `.agent/`. -## Development Install +## Status -Use Node.js 20 or newer and pnpm 10.24.0. +Kernel **0.3.0** is the marketing release. Install: ```bash -pnpm install -pnpm build +npm install -g @mattbaconz/kernel ``` -Run the CLI from source after building: +If you are developing from this source repository, keep using `pnpm build` / packed install until your checkout is published. -```bash -node dist/cli/index.js --help -``` +## What Kernel writes + +| Artifact | Path | Purpose | +|----------|------|---------| +| Task contract | `.agent/contracts/`, `.agent/state/current-task.md` | What was asked, non-goals, risks, done criteria | +| Evidence ledger | `.agent/evidence/` | What was checked before claiming done | +| Handoff packet | `.agent/handoffs/` | What is left when switching agents or pausing | +| Repo maps | `.agent/maps/` | Commands, tests, risk surfaces | +| Core skills | `.agent/skills/` (compiled to ADE paths) | On-demand Agent Skills for the workflow | -## Local Packed Install +## Install (development) -For release-artifact testing without publishing: +Use Node.js 20+ and pnpm 10.24.0. ```bash +pnpm install pnpm build -npm pack -npm install -g ./mattbaconz-kernel-0.1.0.tgz -kernel --help +node dist/cli/index.js --help ``` -Once published, the intended package install name is: +Once published: ```bash npm install -g @mattbaconz/kernel ``` -The project also includes an automated packed-artifact check: +For packed-artifact testing without publishing: ```bash -pnpm verify:packed +pnpm build +npm pack +npm install -g ./mattbaconz-kernel-*.tgz +kernel --help ``` -## Quickstart In A Repository +## Quickstart -Initialize Kernel: +Default path installs the **Core** skill pack (`mvp`: six skills), not the full advanced set. ```bash kernel init -kernel skill generate --set lint-ready +kernel skill generate kernel map kernel compile all kernel validate ``` -Create work artifacts: +Create the paper trail: ```bash kernel task new --type feature --goal "Describe the change" @@ -77,27 +71,23 @@ kernel evidence new --task current --claim "Describe what was verified" kernel handoff new --task current ``` -Run quality checks: +Quality checks: ```bash kernel validate --json kernel skill lint --json kernel eval --json -kernel schema versions -kernel schema list -kernel schema path skill-eval-result -kernel schema show skill-eval-result --json ``` -## Adapter Compilation +Advanced users can generate the full skill library with `kernel skill generate --set lint-ready`. -Compile every priority ADE adapter: +## Adapter compilation ```bash kernel compile all ``` -Compile one adapter: +Or one ADE: ```bash kernel compile codex @@ -112,9 +102,7 @@ kernel compile windsurf kernel compile junie ``` -## Development Checks - -Run all local checks before pushing: +## Development checks ```bash pnpm test @@ -124,26 +112,18 @@ pnpm build pnpm verify:packed ``` -CI runs the same core checks on `main` and pull requests. - -## Release Readiness - -Kernel is not published to npm yet. Release gates, trusted-publishing setup notes, provenance expectations, and rollback checks are documented in `RELEASE.md`. +## JSON schemas -## JSON Outputs And Schemas - -Machine-readable command outputs include `schemaVersion: 1`. - -Discover schemas: +Machine-readable outputs include `schemaVersion: 1`. Schemas live under `schemas/json/v1/`. ```bash kernel schema versions --json kernel schema list --json -kernel schema path validation-result --json -kernel schema show validation-result --json ``` -Versioned schemas live under `schemas/json/v1/`. +## Documentation + +- Five-minute onboarding: [`docs/kernel-in-5-minutes.md`](docs/kernel-in-5-minutes.md) ## Public Repository Boundary @@ -155,7 +135,7 @@ See `CONTRIBUTING.md`. This repository uses Kernel's own task/evidence workflow ## Security -See `SECURITY.md` for supported reporting channels and security handling expectations. +See `SECURITY.md`. ## License diff --git a/RELEASE.md b/RELEASE.md index 997665f..3c22e1c 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,13 +1,14 @@ # Release Checklist -Kernel is not published to npm yet. This checklist prepares `@mattbaconz/kernel` for a future public npm release without enabling publication now. +This checklist publishes `@mattbaconz/kernel` from the public `mattbaconz/kernel` repository using npm Trusted Publishing. ## Current Gate -- Do not publish while `package.json` has `"private": true`. -- Do not remove `"private": true` except in a dedicated npm publication task. +- Package metadata is publishable (`private` must not be `true`). +- Publish only from the public `mattbaconz/kernel` repository via trusted publishing. - Do not publish from the private `mattbaconz/kernel-skills` repository. -- Use the public `mattbaconz/kernel` repository as the trusted publishing source. +- Use workflow `npm-release.yml` with explicit `enable_publish: true` and matching `publish_confirmation`. +- Do not publish while `package.json` has `"private": true`. ## Package Metadata @@ -16,7 +17,7 @@ Kernel is not published to npm yet. This checklist prepares `@mattbaconz/kernel` - Copyright: `Copyright 2026 mattbaconz` - Package files: `dist/` and `schemas/` - Public package access: configured with `publishConfig.access: public` -- npm package remains unpublished until a separate explicit release task. +- Current marketing release target: `@mattbaconz/kernel@0.3.0` (npm already has earlier versions). ## Required Verification @@ -105,27 +106,23 @@ Publication behavior: ## One-Time Bootstrap -The first npm publication is different because `@mattbaconz/kernel` does not exist on the registry yet. - -If the package still returns `E404`, handle the one-time bootstrap in a separate explicit task: +`@mattbaconz/kernel` already exists on npm (first publish completed). Trusted publishing and future releases use the normal manual workflow below. -1. Verify the public repository is the source checkout. -2. Verify the package metadata points to `https://github.com/mattbaconz/kernel.git`. -3. Remove `"private": true` only in that task. -4. Run the full verification list and inspect `npm pack --dry-run --json`. -5. Publish once only after the user explicitly approves publication. -6. Configure trusted publishing immediately after the package exists. -7. Use the normal manual workflow for future releases. +Historical note: the first publication required removing `"private": true`, a one-time publish, then configuring the trusted publisher for `mattbaconz/kernel` / `npm-release.yml` / `npm-release`. ## Tag And Release -Before npm publication: +Before npm publication of a new version (for example `0.3.0`): 1. Confirm `CHANGELOG.md` has the intended version notes. 2. Confirm `package.json` version matches the release tag. -3. Create or verify the release tag, for example `v0.1.0`. -4. Confirm public CI is green on the tagged commit. -5. Create a GitHub Release after the tag is final. +3. Sync private source → public `mattbaconz/kernel` and wait for public CI green. +4. Create or verify the release tag, for example `v0.3.0`. +5. Run `.github/workflows/npm-release.yml` with: + - `enable_publish: true` + - `publish_confirmation: @mattbaconz/kernel@0.3.0` + - `expected_version: 0.3.0` +6. Create a GitHub Release after the tag is final. ## Rollback diff --git a/docs/kernel-in-5-minutes.md b/docs/kernel-in-5-minutes.md new file mode 100644 index 0000000..c2bc504 --- /dev/null +++ b/docs/kernel-in-5-minutes.md @@ -0,0 +1,64 @@ +# Kernel in 5 minutes + +**Kernel is a paper trail for AI coding agents** — AGENTS.md with a memory. + +## What you get + +Three durable artifacts in git: + +1. **Task contract** — what was asked, non-goals, done criteria (`.agent/state/`, `.agent/contracts/`) +2. **Evidence ledger** — what was checked before "done" (`.agent/evidence/`) +3. **Handoff packet** — what is left when switching tools or pausing (`.agent/handoffs/`) + +Plus a **Core** skill pack (six skills) compiled into the open Agent Skills format each ADE already reads. + +## Install + +Once published: + +```bash +npm install -g @mattbaconz/kernel +``` + +From this repo today: + +```bash +pnpm install && pnpm build +node dist/cli/index.js --help +``` + +## Initialize a repo + +```bash +kernel init +kernel skill generate +kernel map +kernel compile all +kernel validate +``` + +Default skill set is **Core** (`mvp`). Use `--set lint-ready` only if you want the full advanced library. + +## Everyday loop + +```bash +kernel task new --type feature --goal "Describe the change" +# ... implement ... +kernel evidence new --task current --claim "Describe what was verified" +# if pausing or switching tools: +kernel handoff new --task current +``` + +## Mental model + +```txt +Vague ask → task contract → minimal change → verify → evidence → (handoff if needed) +``` + +Kernel is not a competing skills format. It is the **stateful layer** on top of AGENTS.md / Agent Skills. + +## Next + +- Full README: repository root `README.md` +- Deep docs: `kernel_obsidian_vault/` +- Release gates: `RELEASE.md` diff --git a/package.json b/package.json index c194d34..888bb1e 100644 --- a/package.json +++ b/package.json @@ -1,9 +1,23 @@ { "name": "@mattbaconz/kernel", - "version": "0.2.0", - "description": "Kernel CLI: a repo-local quality system and portable operating layer for coding agents.", + "version": "0.3.0", + "description": "A paper trail for AI coding agents — task contracts, verification evidence, and handoffs that survive across tools.", "type": "module", "license": "Apache-2.0", + "keywords": [ + "agents", + "agent-skills", + "agents-md", + "ai-coding", + "codex", + "claude-code", + "cursor", + "github-copilot", + "kiro", + "task-contract", + "verification", + "handoff" + ], "repository": { "type": "git", "url": "https://github.com/mattbaconz/kernel.git" diff --git a/src/adapters/canonical-skills.ts b/src/adapters/canonical-skills.ts index b9ddc4a..8fbb73d 100644 --- a/src/adapters/canonical-skills.ts +++ b/src/adapters/canonical-skills.ts @@ -45,23 +45,89 @@ export function skillBodyWithoutFrontmatter(content: string): string { return match ? content.slice(match[0].length).trimStart() : content; } -export function renderCursorRuleFromSkill(skillName: string, content: string): string { +export interface CursorRuleFrontmatter { + description?: string; + globs?: string; + alwaysApply?: boolean; +} + +export function renderCursorRuleFromSkill( + skillName: string, + content: string, + frontmatter: CursorRuleFrontmatter = {} +): string { const body = skillBodyWithoutFrontmatter(content); const title = body.match(/^#\s+(.+)$/m)?.[1] ?? skillName; - return [`# ${title}`, '', body.replace(/^#\s+.+\n?/m, '').trim()].join('\n'); + const bodyWithoutTitle = body.replace(/^#\s+.+\n?/m, '').trim(); + const yamlLines = [ + frontmatter.description !== undefined ? `description: ${JSON.stringify(frontmatter.description)}` : null, + frontmatter.globs !== undefined ? `globs: ${JSON.stringify(frontmatter.globs)}` : null, + frontmatter.alwaysApply !== undefined ? `alwaysApply: ${frontmatter.alwaysApply}` : null + ].filter((line): line is string => line !== null); + + const parts: string[] = []; + if (yamlLines.length > 0) { + parts.push('---', ...yamlLines, '---', ''); + } + parts.push(`# ${title}`, '', bodyWithoutTitle); + return parts.join('\n'); } export function resolveCursorRuleContent( skills: CanonicalSkill[], skillName: string, fallback: string, - manualSectionLines: string[] + manualSectionLines: string[], + frontmatter: CursorRuleFrontmatter = {} ): string { const skill = findCanonicalSkill(skills, skillName); - const core = skill ? renderCursorRuleFromSkill(skill.name, skill.content) : fallback; + const core = skill ? renderCursorRuleFromSkill(skill.name, skill.content, frontmatter) : withCursorFrontmatter(fallback, frontmatter); return [...core.split('\n'), '', ...manualSectionLines, ''].join('\n'); } +function withCursorFrontmatter(content: string, frontmatter: CursorRuleFrontmatter): string { + if ( + frontmatter.description === undefined && + frontmatter.globs === undefined && + frontmatter.alwaysApply === undefined + ) { + return content; + } + + return renderCursorRuleFromSkill('fallback', `${content}\n`, frontmatter); +} + +export function renderSharedAgentsSkillOutputs(canonicalSkills: CanonicalSkill[]): Array<{ + path: string; + content: string; + generated: true; + preserveManualSections: true; +}> { + return canonicalSkills.map((skill) => ({ + path: `.agents/skills/${skill.name}/SKILL.md`, + content: skill.content, + generated: true as const, + preserveManualSections: true as const + })); +} + +export function renderNativeSkillOutputs( + baseDir: string, + canonicalSkills: CanonicalSkill[] +): Array<{ + path: string; + content: string; + generated: true; + preserveManualSections: true; +}> { + return canonicalSkills.map((skill) => ({ + path: `${baseDir.replace(/\/$/, '')}/${skill.name}/SKILL.md`, + content: skill.content, + generated: true as const, + preserveManualSections: true as const + })); +} + async function pathExists(path: string): Promise { try { await access(path); diff --git a/src/adapters/claude.ts b/src/adapters/claude.ts index 911ec31..db85a83 100644 --- a/src/adapters/claude.ts +++ b/src/adapters/claude.ts @@ -80,7 +80,7 @@ function renderClaudeMd(projectName: string): string { return [ '# CLAUDE.md', '', - 'This repository uses **Kernel** for repo-local task contracts, verification evidence, and handoffs.', + 'This repository uses **Kernel** — a paper trail for AI coding agents (task contracts, verification evidence, and handoffs).', '', `Project: ${projectName}`, '', diff --git a/src/adapters/codex.ts b/src/adapters/codex.ts index 0043183..1b4cbb7 100644 --- a/src/adapters/codex.ts +++ b/src/adapters/codex.ts @@ -1,3 +1,4 @@ +import { renderSharedAgentsSkillOutputs } from './canonical-skills.js'; import type { KernelAdapter } from './types.js'; import { canonicalSourceList, manualSection, primeDirective } from './common.js'; @@ -11,18 +12,10 @@ export const codexAdapter: KernelAdapter = { content: renderCodexAgents(projectName), generated: true as const, preserveManualSections: true - } + }, + ...renderSharedAgentsSkillOutputs(canonicalSkills) ]; - for (const skill of canonicalSkills) { - outputs.push({ - path: `.agents/skills/${skill.name}/SKILL.md`, - content: skill.content, - generated: true as const, - preserveManualSections: true - }); - } - if (canonicalSkills.length === 0) { outputs.push({ path: '.agents/skills/kernel-core/SKILL.md', @@ -40,7 +33,7 @@ function renderCodexAgents(projectName: string): string { return [ '# AGENTS.md', '', - 'This repository uses **Kernel** for repo-local task contracts, verification evidence, and agent handoffs.', + 'This repository uses **Kernel** — a paper trail for AI coding agents (task contracts, verification evidence, and handoffs).', '', `Project: ${projectName}`, '', diff --git a/src/adapters/common.ts b/src/adapters/common.ts index 5ceea24..b23a545 100644 --- a/src/adapters/common.ts +++ b/src/adapters/common.ts @@ -32,7 +32,7 @@ export function renderKernelBootstrapAgents(projectName: string, workflowLabel: return [ '# AGENTS.md', '', - 'This repository uses **Kernel** for repo-local task contracts, verification evidence, and agent handoffs.', + 'This repository uses **Kernel** — a paper trail for AI coding agents (task contracts, verification evidence, and handoffs).', '', `Project: ${projectName}`, '', diff --git a/src/adapters/cursor.ts b/src/adapters/cursor.ts index fb684c7..8115308 100644 --- a/src/adapters/cursor.ts +++ b/src/adapters/cursor.ts @@ -1,4 +1,8 @@ -import { resolveCursorRuleContent } from './canonical-skills.js'; +import { + renderNativeSkillOutputs, + renderSharedAgentsSkillOutputs, + resolveCursorRuleContent +} from './canonical-skills.js'; import type { KernelAdapter } from './types.js'; import { manualSection, primeDirective } from './common.js'; @@ -6,16 +10,20 @@ export const cursorAdapter: KernelAdapter = { name: 'cursor', render({ config, canonicalSkills }) { const projectName = config.project.name; - return [ + const outputs = [ { path: '.cursor/rules/kernel-core.mdc', content: resolveCursorRuleContent( canonicalSkills, 'kernel-core', renderCoreRule(projectName), - manualSection() + manualSection(), + { + description: 'Kernel core paper trail: task contracts, evidence, and handoffs.', + alwaysApply: true + } ), - generated: true, + generated: true as const, preserveManualSections: true }, { @@ -24,9 +32,12 @@ export const cursorAdapter: KernelAdapter = { canonicalSkills, 'verify-lattice', renderQualityRule(projectName), - manualSection() + manualSection(), + { + description: 'Kernel verification and evidence rules before claiming completion.' + } ), - generated: true, + generated: true as const, preserveManualSections: true }, { @@ -35,12 +46,40 @@ export const cursorAdapter: KernelAdapter = { canonicalSkills, 'risk-map', renderSecurityRule(projectName), - manualSection() + manualSection(), + { + description: 'Kernel high-risk path and destructive-command caution.' + } ), - generated: true, + generated: true as const, preserveManualSections: true - } + }, + ...renderNativeSkillOutputs('.cursor/skills', canonicalSkills), + ...renderSharedAgentsSkillOutputs(canonicalSkills) ]; + + if (canonicalSkills.length === 0) { + outputs.push({ + path: '.cursor/skills/kernel-core/SKILL.md', + content: [ + '---', + 'name: kernel-core', + 'description: "Use before and after non-trivial coding-agent tasks in Kernel repositories. Do not use for trivial one-line edits unless high-risk."', + '---', + '', + '# kernel-core', + '', + renderCoreRule(projectName), + '', + ...manualSection(), + '' + ].join('\n'), + generated: true as const, + preserveManualSections: true + }); + } + + return outputs; } }; @@ -78,6 +117,6 @@ function renderSecurityRule(projectName: string): string { '', '- Inspect `.agent/maps/risk.json` when present.', '- Do not silently perform destructive operations.', - '- Escalate verification for auth, billing, migrations, CI, and publishing changes.' + '- Escalate verification for auth, secrets, migrations, and public APIs.' ].join('\n'); } diff --git a/src/adapters/gemini.ts b/src/adapters/gemini.ts index d54f53e..510ba92 100644 --- a/src/adapters/gemini.ts +++ b/src/adapters/gemini.ts @@ -33,7 +33,7 @@ function renderGeminiMd(projectName: string, canonicalSkills: { name: string }[] return [ '# GEMINI.md', '', - 'This repository uses **Kernel** for repo-local task contracts, verification evidence, and handoffs.', + 'This repository uses **Kernel** — a paper trail for AI coding agents (task contracts, verification evidence, and handoffs).', '', `Project: ${projectName}`, '', diff --git a/src/adapters/github-copilot.ts b/src/adapters/github-copilot.ts index 510324f..2dd6c5c 100644 --- a/src/adapters/github-copilot.ts +++ b/src/adapters/github-copilot.ts @@ -1,3 +1,4 @@ +import { renderNativeSkillOutputs, renderSharedAgentsSkillOutputs } from './canonical-skills.js'; import type { KernelAdapter } from './types.js'; import { kernelProcedure, manualSection, primeDirective, skillFrontmatter } from './common.js'; @@ -23,30 +24,21 @@ export const githubCopilotAdapter: KernelAdapter = { content: renderReviewInstructions(projectName), generated: true as const, preserveManualSections: true - } + }, + ...renderNativeSkillOutputs('.github/skills', canonicalSkills), + ...renderSharedAgentsSkillOutputs(canonicalSkills) ]; - if (canonicalSkills.length > 0) { - for (const skill of canonicalSkills) { - outputs.push({ - path: `.github/skills/${skill.name}/SKILL.md`, - content: skill.content, - generated: true as const, - preserveManualSections: true - }); - } - return outputs; - } - - return [ - ...outputs, - { + if (canonicalSkills.length === 0) { + outputs.push({ path: '.github/skills/kernel-core/SKILL.md', content: renderCopilotSkill(projectName), generated: true as const, preserveManualSections: true - } - ]; + }); + } + + return outputs; } }; @@ -54,7 +46,7 @@ function renderCopilotInstructions(projectName: string): string { return [ '# GitHub Copilot Instructions', '', - 'This repository uses **Kernel** for repo-local agent quality artifacts.', + 'This repository uses **Kernel** — a paper trail for AI coding agents (task contracts, verification evidence, and handoffs).', '', `Project: ${projectName}`, '', diff --git a/src/adapters/junie.ts b/src/adapters/junie.ts index 3805c0f..ba81a25 100644 --- a/src/adapters/junie.ts +++ b/src/adapters/junie.ts @@ -20,7 +20,7 @@ function renderJunieAgents(projectName: string): string { return [ '# AGENTS.md', '', - 'This repository uses **Kernel** for repo-local task contracts, verification evidence, and handoffs.', + 'This repository uses **Kernel** — a paper trail for AI coding agents (task contracts, verification evidence, and handoffs).', '', `Project: ${projectName}`, '', diff --git a/src/adapters/kiro.ts b/src/adapters/kiro.ts index 3d13fa9..26a4fa2 100644 --- a/src/adapters/kiro.ts +++ b/src/adapters/kiro.ts @@ -1,9 +1,10 @@ +import { renderNativeSkillOutputs, renderSharedAgentsSkillOutputs } from './canonical-skills.js'; import type { KernelAdapter } from './types.js'; import { canonicalSourceList, manualSection, primeDirective } from './common.js'; export const kiroAdapter: KernelAdapter = { name: 'kiro', - render({ config }) { + render({ config, canonicalSkills }) { const projectName = config.project.name; return [ { @@ -29,7 +30,9 @@ export const kiroAdapter: KernelAdapter = { content: renderKernelRequirements(projectName), generated: true, preserveManualSections: true - } + }, + ...renderNativeSkillOutputs('.kiro/skills', canonicalSkills), + ...renderSharedAgentsSkillOutputs(canonicalSkills) ]; } }; diff --git a/src/cli/index.ts b/src/cli/index.ts index 288a066..9f24065 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -49,8 +49,8 @@ export function createKernelProgram(): Command { program .name('kernel') - .description('Repo-local quality system and portable operating layer for coding agents.') - .version('0.2.0'); + .description('A paper trail for AI coding agents — task contracts, evidence, and handoffs.') + .version('0.3.0'); program .command('init') diff --git a/src/core/eval.ts b/src/core/eval.ts index 85960b1..2b3498f 100644 --- a/src/core/eval.ts +++ b/src/core/eval.ts @@ -1,9 +1,11 @@ import { join } from 'node:path'; +import { readFile } from 'node:fs/promises'; import { loadKernelConfig } from './config.js'; import { type KernelWriteAction, writeKernelFile } from './fs.js'; import { formatKernelJsonResult } from './json-output.js'; import { lintKernelSkills, type SkillLintIssue, type SkillRegressionFixturePlan } from './skills.js'; +import { resolveCanonicalPaths } from './paths.js'; export type SkillEvalStatus = 'pass' | 'warn' | 'fail'; export type SkillEvalCaseStatus = 'pass' | 'skip' | 'fail'; @@ -216,7 +218,7 @@ export function createStaticSkillEvalRunner(): SkillEvalRunner { return { name: 'static-noop', mode: 'static', - run: (fixture) => { + run: async (fixture, context) => { if ( fixture.expectedActivates && fixture.expectedSkills.length > 0 && @@ -229,6 +231,13 @@ export function createStaticSkillEvalRunner(): SkillEvalRunner { }; } + if (fixture.artifactShape !== undefined) { + const shapeResult = await evaluateArtifactShape(context.rootDir, fixture); + if (shapeResult !== null) { + return shapeResult; + } + } + return { outcome: 'pass', executed: false, @@ -238,6 +247,61 @@ export function createStaticSkillEvalRunner(): SkillEvalRunner { }; } +async function evaluateArtifactShape( + rootDir: string, + fixture: SkillRegressionFixturePlan +): Promise { + const shape = fixture.artifactShape; + if (shape === undefined) { + return null; + } + + const config = await loadKernelConfig(rootDir); + const paths = resolveCanonicalPaths(rootDir, config); + const skillPath = join(paths.skillsDir, fixture.skillName, 'SKILL.md'); + + let content: string; + try { + content = await readFile(skillPath, 'utf8'); + } catch { + return { + outcome: 'fail', + executed: true, + reason: `Artifact shape check failed: missing canonical skill at \`${fixture.skillName}/SKILL.md\`.` + }; + } + + for (const section of shape.requiredSections) { + if (!new RegExp(`^##\\s+${escapeRegExp(section)}\\s*$`, 'im').test(content)) { + return { + outcome: 'fail', + executed: true, + reason: `Artifact shape check failed: missing \`## ${section}\` in ${fixture.skillName}.` + }; + } + } + + for (const needle of shape.bodyContains) { + if (!content.includes(needle)) { + return { + outcome: 'fail', + executed: true, + reason: `Artifact shape check failed: expected body to contain \`${needle}\` in ${fixture.skillName}.` + }; + } + } + + return { + outcome: 'pass', + executed: true, + reason: 'Static artifact-shape checks passed against canonical skill body.' + }; +} + +function escapeRegExp(value: string): string { + return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); +} + export function formatSkillEvalResult(result: SkillEvalResult): string { const lines = [ `Skill eval status: ${result.status}`, diff --git a/src/core/init.ts b/src/core/init.ts index 2631696..bfc53af 100644 --- a/src/core/init.ts +++ b/src/core/init.ts @@ -131,7 +131,7 @@ export function renderDefaultAgentsMd(): string { return [ '# AGENTS.md', '', - 'This repository uses **Kernel**, a repo-local quality system and portable operating layer for coding agents.', + 'This repository uses **Kernel** — a paper trail for AI coding agents (task contracts, verification evidence, and handoffs).', '', '## Prime directive', '', diff --git a/src/core/skill-generator.ts b/src/core/skill-generator.ts index 47ad8e5..4789048 100644 --- a/src/core/skill-generator.ts +++ b/src/core/skill-generator.ts @@ -32,6 +32,7 @@ export interface GeneratedSkillFileResult { export type SkippedSkillDocReasonCode = | 'invalid_skill_filename' | 'missing_output_artifact' + | 'missing_skill_example' | 'missing_skill_output' | 'missing_skill_purpose' | 'missing_skill_trigger' @@ -224,12 +225,20 @@ function normalizeSkillDocumentation(sourceContent: string): string { } function deriveDescription(body: string): string { - const purpose = getSectionContent(body, 'Purpose') ?? 'Use when the Kernel skill matches the current task.'; - const firstParagraph = purpose - .split(/\r?\n\s*\r?\n/u)[0] - .replace(/\s+/gu, ' ') - .trim(); - const trigger = firstParagraph.length > 0 ? firstParagraph : 'Use when the Kernel skill matches the current task.'; + const triggerSection = getSectionContent(body, 'Trigger'); + const purpose = getSectionContent(body, 'Purpose'); + const candidates = [triggerSection, purpose] + .filter((value): value is string => value !== null && value.trim().length > 0) + .map((value) => + value + .split(/\r?\n\s*\r?\n/u)[0] + .replace(/\s+/gu, ' ') + .trim() + ) + .filter((value) => value.length > 0); + + const withTriggerPhrase = candidates.find((value) => /\bUse (when|before|after|for)\b/i.test(value)); + const trigger = withTriggerPhrase ?? candidates[0] ?? 'Use when the Kernel skill matches the current task.'; if (/\b(Do not use|Do not trigger|unless)\b/i.test(trigger)) { return trigger; @@ -238,6 +247,11 @@ function deriveDescription(body: string): string { return `${trigger} Do not trigger it for unrelated work just because the skill exists.`; } +/** Shared Core pack names — used by lint/eval gates for market-ready skills. */ +export function isCoreSkillName(skillName: string): boolean { + return (MVP_SKILL_NAMES as readonly string[]).includes(skillName); +} + function getSkippedSkillDocReasons(skillName: string, sourceContent: string): SkippedSkillDocReason[] { const body = normalizeSkillDocumentation(sourceContent); const description = deriveDescription(body); @@ -273,6 +287,13 @@ function getSkippedSkillDocReasons(skillName: string, sourceContent: string): Sk }); } + if (isCoreSkillName(skillName) && !hasSection(body, 'Example')) { + reasons.push({ + code: 'missing_skill_example', + message: 'Core skill docs must include a `## Example` section with a concrete worked example.' + }); + } + if (!/\bUse (when|before|after|for)\b/i.test(description)) { reasons.push({ code: 'missing_skill_trigger', diff --git a/src/core/skills.ts b/src/core/skills.ts index 6cd6068..d7305ee 100644 --- a/src/core/skills.ts +++ b/src/core/skills.ts @@ -6,20 +6,24 @@ import { parse as parseYaml } from 'yaml'; import { loadKernelConfig, type KernelConfig } from './config.js'; import { formatKernelJsonResult } from './json-output.js'; import { resolveCanonicalPaths } from './paths.js'; +import { isCoreSkillName } from './skill-generator.js'; export type SkillLintStatus = 'pass' | 'warn' | 'fail'; export type SkillLintIssueCode = + | 'generic_related_skills' | 'invalid_skill_fixture' | 'invalid_skill_frontmatter' | 'missing_do_not_use_condition' | 'missing_output_artifact' | 'missing_skill_description' + | 'missing_skill_example' | 'missing_skill_file' | 'missing_skill_frontmatter' | 'missing_skill_name' | 'missing_skill_section' | 'missing_trigger_description' | 'overbroad_skill_description' + | 'self_related_skill' | 'skill_fixture_without_skill' | 'skill_heading_mismatch' | 'skill_name_mismatch'; @@ -43,6 +47,12 @@ export interface SkillRegressionFixturePlan { prompt: string; expectedActivates: boolean; expectedSkills: string[]; + artifactShape?: SkillArtifactShapeExpectation; +} + +export interface SkillArtifactShapeExpectation { + requiredSections: string[]; + bodyContains: string[]; } export interface SkillLintResult { @@ -278,6 +288,15 @@ function lintRequiredSections(skillFile: SkillFile, body: string, issues: SkillL }); } + if (isCoreSkillName(skillFile.directoryName) && !hasSection(body, 'Example')) { + issues.push({ + code: 'missing_skill_example', + severity: 'warning', + path: skillFile.relativePath, + message: 'Core skills must include a `## Example` section with a concrete worked example.' + }); + } + const outputSection = getSectionContent(body, 'Output'); if (outputSection !== null && !/\.agent\//i.test(outputSection) && !/\bno artifact\b/i.test(outputSection)) { issues.push({ @@ -287,6 +306,40 @@ function lintRequiredSections(skillFile: SkillFile, body: string, issues: SkillL message: 'Skill output section should name a concrete `.agent/` artifact or state that no artifact is produced.' }); } + + lintRelatedSkills(skillFile, body, issues); +} + +const GENERIC_RELATED_SKILLS = new Set(['kernel-core', 'verify-lattice', 'evidence-ledger', 'handoff-packet']); + +function lintRelatedSkills(skillFile: SkillFile, body: string, issues: SkillLintIssue[]): void { + const related = getSectionContent(body, 'Related skills'); + if (related === null) { + return; + } + + const links = [...related.matchAll(/\[\[([^\]]+)\]\]/g)].map((match) => match[1]?.trim()).filter(Boolean) as string[]; + if (links.includes(skillFile.directoryName)) { + issues.push({ + code: 'self_related_skill', + severity: 'warning', + path: skillFile.relativePath, + message: 'Related skills must not list the skill itself.' + }); + } + + if ( + isCoreSkillName(skillFile.directoryName) && + links.length === GENERIC_RELATED_SKILLS.size && + links.every((link) => GENERIC_RELATED_SKILLS.has(link)) + ) { + issues.push({ + code: 'generic_related_skills', + severity: 'warning', + path: skillFile.relativePath, + message: 'Core skills must use skill-specific related links, not the shared boilerplate set.' + }); + } } async function discoverSkillRegressionFixtures( @@ -353,21 +406,47 @@ async function parseSkillRegressionFixture( return null; } - const expected = parsed.expected; + const expected = parsed.expected as { + activates: boolean; + skills?: unknown[]; + artifactShape?: unknown; + }; const expectedSkills = Array.isArray(expected.skills) ? expected.skills.filter((value): value is string => typeof value === 'string' && value.trim().length > 0) : []; + const artifactShape = parseArtifactShape(expected.artifactShape); + return { path: relativePath, skillName, name: parsed.name, prompt: parsed.prompt, expectedActivates: expected.activates, - expectedSkills + expectedSkills, + ...(artifactShape !== undefined ? { artifactShape } : {}) }; } +function parseArtifactShape(value: unknown): SkillArtifactShapeExpectation | undefined { + if (!isRecord(value)) { + return undefined; + } + + const requiredSections = Array.isArray(value.requiredSections) + ? value.requiredSections.filter((entry): entry is string => typeof entry === 'string' && entry.trim().length > 0) + : []; + const bodyContains = Array.isArray(value.bodyContains) + ? value.bodyContains.filter((entry): entry is string => typeof entry === 'string' && entry.trim().length > 0) + : []; + + if (requiredSections.length === 0 && bodyContains.length === 0) { + return undefined; + } + + return { requiredSections, bodyContains }; +} + function addInvalidFixtureIssue(path: string, issues: SkillLintIssue[]): void { issues.push({ code: 'invalid_skill_fixture', diff --git a/tests/adapter-compiler.test.ts b/tests/adapter-compiler.test.ts index f7fcf99..69c2a84 100644 --- a/tests/adapter-compiler.test.ts +++ b/tests/adapter-compiler.test.ts @@ -42,7 +42,7 @@ describe('codexAdapter', () => { # AGENTS.md - This repository uses **Kernel** for repo-local task contracts, verification evidence, and agent handoffs. + This repository uses **Kernel** — a paper trail for AI coding agents (task contracts, verification evidence, and handoffs). Project: Codex Fixture diff --git a/tests/fixtures/eval-skills-config-static/.agent/skills/evidence-ledger/SKILL.md b/tests/fixtures/eval-skills-config-static/.agent/skills/evidence-ledger/SKILL.md index 7b49a11..6ffedd3 100644 --- a/tests/fixtures/eval-skills-config-static/.agent/skills/evidence-ledger/SKILL.md +++ b/tests/fixtures/eval-skills-config-static/.agent/skills/evidence-ledger/SKILL.md @@ -1,24 +1,38 @@ --- name: evidence-ledger -description: Use after implementation, debugging, review, or release work to record claims and proof. Do not use when no claim or verification artifact is needed. +description: Use after verification to record claims and proof. Do not use before any check has been attempted unless capturing a failed reproduction. --- # evidence-ledger ## Purpose -Record claims, commands, verification results, artifacts, and remaining risk for a task. +Use after implementation or debugging to record claims and proof under `.agent/evidence/`. ## Trigger -Use after a task has verification evidence that should be preserved for review or handoff. +Use when recording what was run and what it proved. Do not trigger merely because a task contract exists. ## Workflow -1. Identify the task claim. -2. Record commands and results. -3. Record remaining risks. +1. State the claim. +2. Record commands and exit codes. +3. Record remaining risk. ## Output -Writes `.agent/evidence/.md` when filesystem access is available. +Write a ledger under `.agent/evidence/`. + +## Example + +```md +# Evidence Ledger +Commands: +- pnpm test → exit 0 +Status: verified +``` + +## Related skills + +- [[verify-lattice]] +- [[task-contract]] diff --git a/tests/fixtures/eval-skills-config-static/.agent/skills/kernel-core/SKILL.md b/tests/fixtures/eval-skills-config-static/.agent/skills/kernel-core/SKILL.md index 9906ca9..dfa9cc6 100644 --- a/tests/fixtures/eval-skills-config-static/.agent/skills/kernel-core/SKILL.md +++ b/tests/fixtures/eval-skills-config-static/.agent/skills/kernel-core/SKILL.md @@ -22,3 +22,16 @@ Use when a coding-agent task requires durable context, quality gates, or evidenc ## Output Writes or updates `.agent/state/current-task.md` and `.agent/evidence/` artifacts when filesystem access is available. + +## Example + +```md +# Task Contract +Goal: Add rate limiting. +Done when: tests green and evidence recorded. +``` + +## Related skills + +- [[task-contract]] +- [[evidence-ledger]] diff --git a/tests/fixtures/eval-skills/.agent/skills/evidence-ledger/SKILL.md b/tests/fixtures/eval-skills/.agent/skills/evidence-ledger/SKILL.md index 7b49a11..6ffedd3 100644 --- a/tests/fixtures/eval-skills/.agent/skills/evidence-ledger/SKILL.md +++ b/tests/fixtures/eval-skills/.agent/skills/evidence-ledger/SKILL.md @@ -1,24 +1,38 @@ --- name: evidence-ledger -description: Use after implementation, debugging, review, or release work to record claims and proof. Do not use when no claim or verification artifact is needed. +description: Use after verification to record claims and proof. Do not use before any check has been attempted unless capturing a failed reproduction. --- # evidence-ledger ## Purpose -Record claims, commands, verification results, artifacts, and remaining risk for a task. +Use after implementation or debugging to record claims and proof under `.agent/evidence/`. ## Trigger -Use after a task has verification evidence that should be preserved for review or handoff. +Use when recording what was run and what it proved. Do not trigger merely because a task contract exists. ## Workflow -1. Identify the task claim. -2. Record commands and results. -3. Record remaining risks. +1. State the claim. +2. Record commands and exit codes. +3. Record remaining risk. ## Output -Writes `.agent/evidence/.md` when filesystem access is available. +Write a ledger under `.agent/evidence/`. + +## Example + +```md +# Evidence Ledger +Commands: +- pnpm test → exit 0 +Status: verified +``` + +## Related skills + +- [[verify-lattice]] +- [[task-contract]] diff --git a/tests/fixtures/eval-skills/.agent/skills/kernel-core/SKILL.md b/tests/fixtures/eval-skills/.agent/skills/kernel-core/SKILL.md index 9906ca9..dfa9cc6 100644 --- a/tests/fixtures/eval-skills/.agent/skills/kernel-core/SKILL.md +++ b/tests/fixtures/eval-skills/.agent/skills/kernel-core/SKILL.md @@ -22,3 +22,16 @@ Use when a coding-agent task requires durable context, quality gates, or evidenc ## Output Writes or updates `.agent/state/current-task.md` and `.agent/evidence/` artifacts when filesystem access is available. + +## Example + +```md +# Task Contract +Goal: Add rate limiting. +Done when: tests green and evidence recorded. +``` + +## Related skills + +- [[task-contract]] +- [[evidence-ledger]] diff --git a/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/adapter-compiler.md b/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/adapter-compiler.md index 401bd0f..4a02e21 100644 --- a/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/adapter-compiler.md +++ b/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/adapter-compiler.md @@ -2,27 +2,42 @@ ## Purpose -Use when generating ADE-specific files from canonical Kernel source. +Use when generating ADE-specific files from canonical Kernel source under `.agent/`. Do not use for editing user-authored instruction files that are outside Kernel's generated outputs. ## Trigger -Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. +Use when running or planning `kernel compile`, refreshing adapters after skill changes, or debugging stale ADE files. Do not trigger for ordinary feature work unrelated to adapter outputs. ## Workflow -1. Read `.agent/kernel.yaml`. -2. Generate adapter outputs. -3. Preserve manual sections. -4. Validate freshness. +1. Read `.agent/kernel.yaml` for enabled adapters and generation settings. +2. Ensure canonical skills exist (`kernel skill generate` for the intended set). +3. Run `kernel compile` for the needed ADE(s), preserving `` sections. +4. Validate with `kernel validate` that generated headers and paths look fresh. ## Output -Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. +Generated ADE files (for example `AGENTS.md`, `.agents/skills/`, `.claude/skills/`, `.cursor/rules/`) plus any compile notes. Canonical config stays under `.agent/`. No artifact under `.agent/` is required beyond existing canonical state; say "no artifact" only when compile is dry-run with no writes. + +## Example + +```txt +$ kernel skill generate +$ kernel compile cursor +wrote: .cursor/rules/kernel-core.mdc +wrote: .cursor/skills/kernel-core/SKILL.md +$ kernel validate +status: pass +``` ## Quality bar -- Be specific. -- Prefer observable facts over impressions. -- Record uncertainty explicitly. -- Avoid bloating global instruction files. -- Link output to the current task contract when applicable. +- Never overwrite manual sections between Kernel markers. +- Prefer shared `.agents/skills/` when the ADE reads the open Agent Skills path. +- Re-validate after compile; do not assume silent success. + +## Related skills + +- [[kernel-core]] +- [[repo-cartographer]] +- [[trigger-linter]] diff --git a/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/evidence-ledger.md b/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/evidence-ledger.md index b69e2d7..5068a89 100644 --- a/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/evidence-ledger.md +++ b/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/evidence-ledger.md @@ -2,28 +2,45 @@ ## Purpose -Use after implementation, debugging, review, or release. Records claims and proof. +Use after implementation, debugging, review, or release. Records claims and proof so completion is reviewable. Do not use before any verification has been attempted unless capturing a failed reproduction. ## Trigger -Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. +Use when recording what was run and what it proved. Do not trigger merely because a task contract exists. ## Workflow -1. Record commands. -2. Record exit codes. -3. Record tests and screenshots. -4. Record failures before fixes when applicable. -5. Record remaining risks. +1. State the claim being proven (tied to the task contract). +2. Record commands and exit codes. +3. Record tests, logs, or screenshots that matter. +4. Record failures before fixes when debugging. +5. Record remaining risks and open questions. ## Output -Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. +Write a ledger under `.agent/evidence/` linked to the current task. If filesystem access is unavailable, include the ledger in the agent response. + +## Example + +```md +# Evidence Ledger +Task: current +Claim: Checkout no longer double-charges on retry. +Commands: +- pnpm test -- tests/checkout.test.ts → exit 0 +- pnpm typecheck → exit 0 +Status: verified +Remaining risk: no production canary in this session. +``` ## Quality bar -- Be specific. -- Prefer observable facts over impressions. -- Record uncertainty explicitly. -- Avoid bloating global instruction files. -- Link output to the current task contract when applicable. +- Every claim needs at least one command or observable proof. +- Exit codes beat prose ("tests passed"). +- Remaining risk must be explicit when verification is partial. + +## Related skills + +- [[verify-lattice]] +- [[task-contract]] +- [[handoff-packet]] diff --git a/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/handoff-packet.md b/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/handoff-packet.md index 3149fc3..3ca4d44 100644 --- a/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/handoff-packet.md +++ b/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/handoff-packet.md @@ -2,28 +2,43 @@ ## Purpose -Use when switching ADEs, ending a long session, pausing incomplete work, or before another agent continues. +Use when switching ADEs, ending a long session, pausing incomplete work, or before another agent continues. Do not use for completed work that already has a clear PR description and no leftover tasks. ## Trigger -Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. +Use when continuity matters across sessions or tools. Do not trigger after a fully closed task with evidence and no next actions. ## Workflow -1. Summarize task. +1. Summarize the task and current status. 2. List changed files. -3. List commands run. -4. List known failures. -5. List next actions and do-not-repeat notes. +3. List commands run and key results. +4. List known failures and blockers. +5. List next actions and do-not-repeat notes; write `.agent/handoffs/`. ## Output -Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. +Write a handoff packet under `.agent/handoffs/`. Otherwise include it in the agent response. + +## Example + +```md +# Handoff Packet +Task: rate limiting on public API +Status: in progress — limiter implemented, integration test pending +Changed: src/api/rate-limit.ts, tests/api/rate-limit.test.ts +Commands: pnpm test -- tests/api/rate-limit.test.ts (pass) +Next: add integration check against staging gateway; do not widen to GraphQL yet. +``` ## Quality bar -- Be specific. -- Prefer observable facts over impressions. -- Record uncertainty explicitly. -- Avoid bloating global instruction files. -- Link output to the current task contract when applicable. +- Next actions must be concrete enough for a cold agent to resume. +- Include blockers, not only successes. +- Point to the task contract and evidence paths when they exist. + +## Related skills + +- [[kernel-core]] +- [[evidence-ledger]] +- [[pr-narrator]] diff --git a/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/kernel-core.md b/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/kernel-core.md index f8b2e3f..ab7466f 100644 --- a/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/kernel-core.md +++ b/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/kernel-core.md @@ -6,24 +6,42 @@ Use before and after any non-trivial coding-agent task. Creates or updates a tas ## Trigger -Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. +Use when starting or finishing non-trivial agent work in a Kernel repo. Do not trigger for typo-only or comment-only edits outside high-risk paths. ## Workflow -1. Read or create `.agent/state/current-task.md`. -2. Classify task type and risk. -3. Route to relevant subskills. -4. Require evidence before completion. -5. Create handoff if context is long or work is incomplete. +1. Read `.agent/kernel.yaml` and `.agent/state/current-task.md` (create the task file if missing). +2. Classify task type and risk; keep the change set minimal. +3. Route to `task-contract`, `verify-lattice`, and other skills only when they match the work. +4. Require an evidence ledger before claiming completion. +5. Create a handoff packet if the session ends incomplete or another ADE will continue. ## Output -Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. +Write or update `.agent/state/current-task.md`, and when needed `.agent/contracts/`, `.agent/evidence/`, and `.agent/handoffs/`. If filesystem access is unavailable, include the same content in the agent response. + +## Example + +Request: "Add rate limiting to the public API." + +```md +# Task Contract +Type: feature +Goal: Add rate limiting to public API endpoints without changing auth. +Non-goals: Rewrite the API gateway; change client SDKs. +Verification: unit tests for limiter + one integration check. +Done when: limiter shipped, tests green, evidence ledger recorded. +``` ## Quality bar -- Be specific. -- Prefer observable facts over impressions. -- Record uncertainty explicitly. -- Avoid bloating global instruction files. -- Link output to the current task contract when applicable. +- Keep the task contract short enough to re-read in under a minute. +- Prefer observable done criteria over vague "works" claims. +- Do not expand scope beyond the contract without updating it. + +## Related skills + +- [[task-contract]] +- [[verify-lattice]] +- [[evidence-ledger]] +- [[handoff-packet]] diff --git a/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/task-contract.md b/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/task-contract.md index 7d5254e..9cea91f 100644 --- a/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/task-contract.md +++ b/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/task-contract.md @@ -2,28 +2,45 @@ ## Purpose -Use before non-trivial coding, debugging, refactoring, migration, or review work. Converts vague requests into compact goals, non-goals, assumptions, risks, verification, and done criteria. +Use before non-trivial coding, debugging, refactoring, migration, or review work. Converts vague requests into compact goals, non-goals, assumptions, risks, verification, and done criteria. Do not use for requests that are already a complete, single-step instruction with no ambiguity. ## Trigger -Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. +Use when the user ask is underspecified, multi-step, or high-risk. Do not trigger when the ask is a single explicit edit with clear acceptance criteria already stated. ## Workflow -1. Define task type. -2. Write observable goal. -3. Write non-goals. +1. Set task type (`feature`, `bugfix`, `refactor`, `docs`, `chore`, or similar). +2. Write one observable goal sentence. +3. List non-goals that prevent scope creep. 4. List assumptions as confirmed or unconfirmed. -5. Define verification and done criteria. +5. Define verification steps and done criteria; write `.agent/state/current-task.md` (and optionally `.agent/contracts/`). ## Output -Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. +Write `.agent/state/current-task.md` and, when useful, a dated contract under `.agent/contracts/`. Otherwise include the contract in the agent response (no artifact only if the user forbade file writes). + +## Example + +```md +# Task Contract +Type: bugfix +Goal: Stop checkout from double-charging on retry. +Non-goals: Redesign payment provider abstraction. +Assumptions: Stripe webhook retries are the trigger (unconfirmed). +Risks: payment idempotency keys; production data. +Verification: reproduce with failing test; fix; re-run targeted tests. +Done when: failing test passes and evidence ledger lists commands + exit codes. +``` ## Quality bar -- Be specific. -- Prefer observable facts over impressions. -- Record uncertainty explicitly. -- Avoid bloating global instruction files. -- Link output to the current task contract when applicable. +- Goal must be observable (a reviewer could check it). +- Non-goals are required when the request could expand. +- Unconfirmed assumptions must stay labeled until verified. + +## Related skills + +- [[kernel-core]] +- [[risk-map]] +- [[verify-lattice]] diff --git a/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/verify-lattice.md b/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/verify-lattice.md index 87c1ac8..70403ef 100644 --- a/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/verify-lattice.md +++ b/tests/fixtures/skill-generate-basic/public_docs_fixture/03-skills/verify-lattice.md @@ -2,28 +2,43 @@ ## Purpose -Use before declaring completion. Selects and records the appropriate verification level for the task. +Use before declaring completion. Selects and records the appropriate verification level for the task. Do not use as a substitute for writing an evidence ledger after checks run. ## Trigger -Use this skill when its purpose matches the current task. Do not trigger it for unrelated work just because the skill exists. +Use when implementation looks done and the agent is about to claim success. Do not trigger for exploratory reading with no completion claim. ## Workflow -1. Choose L0-L5 verification. -2. Run or request commands. -3. Record outputs. -4. Mark completion status. -5. List remaining risk. +1. Choose verification level L0–L5 based on risk (L0 skim → L5 full suite / staging). +2. Prefer the cheapest checks that can falsify the claim. +3. Run or request those commands. +4. Record outputs and completion status in the evidence path. +5. List remaining risk explicitly if anything was skipped. ## Output -Write a concise artifact under `.agent/` when filesystem access is available. Otherwise, include the artifact in the agent response. +Record the chosen level and commands under `.agent/evidence/` (or in the response if files are unavailable). Link back to `.agent/state/current-task.md`. + +## Example + +```md +## Verification +Level: L2 (targeted) +Commands: +- pnpm test -- tests/checkout.test.ts (exit 0) +- pnpm typecheck (exit 0) +Status: complete with residual risk — no staging deploy in this session. +``` ## Quality bar -- Be specific. -- Prefer observable facts over impressions. -- Record uncertainty explicitly. -- Avoid bloating global instruction files. -- Link output to the current task contract when applicable. +- Never mark complete at L0 for high-risk paths. +- Record skipped levels as remaining risk, not as success. +- Prefer targeted tests over "full suite" theater when scope is narrow. + +## Related skills + +- [[test-scout]] +- [[evidence-ledger]] +- [[kernel-core]] diff --git a/tests/fixtures/skills-valid/.agent/skills/kernel-core/SKILL.md b/tests/fixtures/skills-valid/.agent/skills/kernel-core/SKILL.md index 9906ca9..b4c016f 100644 --- a/tests/fixtures/skills-valid/.agent/skills/kernel-core/SKILL.md +++ b/tests/fixtures/skills-valid/.agent/skills/kernel-core/SKILL.md @@ -22,3 +22,16 @@ Use when a coding-agent task requires durable context, quality gates, or evidenc ## Output Writes or updates `.agent/state/current-task.md` and `.agent/evidence/` artifacts when filesystem access is available. + +## Example + +```md +# Task Contract +Goal: Fix flaky checkout retry. +Done when: failing test passes and evidence lists commands. +``` + +## Related skills + +- [[task-contract]] +- [[evidence-ledger]] diff --git a/tests/priority-adapters.test.ts b/tests/priority-adapters.test.ts index 9a4b8ff..45a122f 100644 --- a/tests/priority-adapters.test.ts +++ b/tests/priority-adapters.test.ts @@ -66,19 +66,24 @@ describe('priority adapter rendering', () => { expect(cursor.files.map((file) => file.relativePath)).toEqual([ '.cursor/rules/kernel-core.mdc', '.cursor/rules/kernel-quality.mdc', - '.cursor/rules/kernel-security.mdc' + '.cursor/rules/kernel-security.mdc', + '.cursor/skills/kernel-core/SKILL.md', + '.agents/skills/kernel-core/SKILL.md' ]); expect(kiro.files.map((file) => file.relativePath)).toEqual([ '.kiro/steering/kernel.md', '.kiro/steering/verification.md', '.kiro/hooks/kernel-evidence.json', - '.kiro/specs/kernel/requirements.md' + '.kiro/specs/kernel/requirements.md', + '.kiro/skills/kernel-core/SKILL.md', + '.agents/skills/kernel-core/SKILL.md' ]); expect(github.files.map((file) => file.relativePath)).toEqual([ '.github/copilot-instructions.md', '.github/instructions/testing.instructions.md', '.github/instructions/review.instructions.md', - '.github/skills/kernel-core/SKILL.md' + '.github/skills/kernel-core/SKILL.md', + '.agents/skills/kernel-core/SKILL.md' ]); }); @@ -106,7 +111,7 @@ describe('priority adapter rendering', () => { # CLAUDE.md - This repository uses **Kernel** for repo-local task contracts, verification evidence, and handoffs. + This repository uses **Kernel** — a paper trail for AI coding agents (task contracts, verification evidence, and handoffs). Project: Multi Adapter Fixture @@ -132,6 +137,11 @@ describe('priority adapter rendering', () => { { "content": " + --- + description: "Kernel core paper trail: task contracts, evidence, and handoffs." + alwaysApply: true + --- + # kernel-core ## Purpose @@ -176,7 +186,7 @@ describe('priority adapter rendering', () => { # GitHub Copilot Instructions - This repository uses **Kernel** for repo-local agent quality artifacts. + This repository uses **Kernel** — a paper trail for AI coding agents (task contracts, verification evidence, and handoffs). Project: Multi Adapter Fixture @@ -220,10 +230,12 @@ describe('compileAdapters', () => { '.cursor/rules/kernel-core.mdc', '.cursor/rules/kernel-quality.mdc', '.cursor/rules/kernel-security.mdc', + '.cursor/skills/kernel-core/SKILL.md', '.kiro/steering/kernel.md', '.kiro/steering/verification.md', '.kiro/hooks/kernel-evidence.json', '.kiro/specs/kernel/requirements.md', + '.kiro/skills/kernel-core/SKILL.md', '.github/copilot-instructions.md', '.github/instructions/testing.instructions.md', '.github/instructions/review.instructions.md', diff --git a/tests/skill-generator.test.ts b/tests/skill-generator.test.ts index f8adafb..f405ffe 100644 --- a/tests/skill-generator.test.ts +++ b/tests/skill-generator.test.ts @@ -45,7 +45,8 @@ describe('generateCanonicalSkills', () => { const kernelCore = await readFile(join(rootDir, '.agent', 'skills', 'kernel-core', 'SKILL.md'), 'utf8'); expect(kernelCore).toContain('name: kernel-core'); expect(kernelCore).toContain('Use before and after any non-trivial coding-agent task.'); - expect(kernelCore).toContain('Write a concise artifact under `.agent/`'); + expect(kernelCore).toContain('.agent/state/current-task.md'); + expect(kernelCore).toContain('## Example'); expect(kernelCore).toContain(MANUAL_START); expect(kernelCore).toContain(MANUAL_END); @@ -54,7 +55,7 @@ describe('generateCanonicalSkills', () => { 'utf8' ); expect(adapterCompiler).toContain( - 'description: "Use when generating ADE-specific files from canonical Kernel source. Do not trigger it for unrelated work just because the skill exists."' + 'description: "Use when running or planning `kernel compile`, refreshing adapters after skill changes, or debugging stale ADE files. Do not trigger for ordinary feature work unrelated to adapter outputs."' ); const lintResult = await lintKernelSkills(rootDir, { strict: true }); diff --git a/tests/validate.test.ts b/tests/validate.test.ts index 3b2453c..a00a3b6 100644 --- a/tests/validate.test.ts +++ b/tests/validate.test.ts @@ -152,7 +152,7 @@ describe('validateKernel', () => { expect(result.status).toBe('warn'); expect(result.errorCount).toBe(0); - expect(result.issues.filter((issue) => issue.code === 'missing_adapter_output')).toHaveLength(18); + expect(result.issues.filter((issue) => issue.code === 'missing_adapter_output')).toHaveLength(19); expect(result.issues.filter((issue) => issue.code === 'missing_adapter_output').map((issue) => issue.path)).toEqual([ '.agents/skills/kernel-core/SKILL.md', '.claude/skills/kernel-core/SKILL.md', @@ -162,6 +162,7 @@ describe('validateKernel', () => { '.cursor/rules/kernel-core.mdc', '.cursor/rules/kernel-quality.mdc', '.cursor/rules/kernel-security.mdc', + '.cursor/skills/kernel-core/SKILL.md', '.github/copilot-instructions.md', '.github/instructions/review.instructions.md', '.github/instructions/testing.instructions.md',