ai-runtime-kit 0.5.0

package/runtime/memory/runtime/context-loading.md

@@ -0,0 +1,107 @@
+# Context Loading Strategy
+
+## Purpose
+
+Define what context AI agents should load for different workflow actions.
+
+## Always Load
+
+- `.ai/runtime/INDEX.md`
+- `.ai/runtime/memory/engineering/principles.md`
+- `.ai/project/memory/engineering/conventions.md`
+- `.ai/project/memory/core/tech-stack.md`
+- `.ai/project/STATE.md`
+
+## Feature Implementation
+
+Load:
+
+- relevant feature spec
+- relevant plan
+- relevant task
+- related contracts
+- related skills from BOTH `.ai/runtime/skills/**` (kit) and
+  `.ai/project/skills/**` (project)
+- related rules from BOTH `.ai/runtime/rules/<language>/*.md`
+  (kit) and `.ai/project/rules/<language>/*.md` (project), for
+  any language whose files the task touches
+- related hooks from BOTH `.ai/runtime/hooks/<phase>-<agent>/*/HOOK.md`
+  (kit) and `.ai/project/hooks/<phase>-<agent>/*/HOOK.md`
+  (project), matching the current agent transition and
+  `appliesWhen`
+- executor agent
+
+Project-side files take precedence on path collision.
+
+Avoid loading unrelated specs, plans, or completed tasks.
+
+## Review
+
+Load:
+
+- feature spec
+- plan if available
+- related contracts
+- git diff
+- verification result
+- reviewer agent
+- `pre-reviewer/*` and `post-reviewer/*` hooks from BOTH
+  `.ai/runtime/hooks/` (kit) and `.ai/project/hooks/` (project)
+  matching the spec's `appliesWhen`
+
+## Verification
+
+Load:
+
+- verifier agent
+- related contracts
+- verification command result
+- changed files summary
+
+## Task Discovery
+
+Load:
+
+- `.ai/runtime/INDEX.md`
+- `.ai/project/tasks/TASK_STATUS.md`
+- task files only when needed
+- related plans/specs only for candidate TODO tasks
+
+## Rules
+
+- Prefer narrow context over broad context.
+- Do not load all `.ai/**` unless doing repository-wide workflow audit.
+- Load contracts before modifying public APIs.
+- Load ADRs before reversing architecture decisions.
+
+## Memory Layer Loading
+
+### Feature Development
+
+Load:
+
+- core/
+- engineering/
+- product/
+
+### Refactor Work
+
+Load:
+
+- architecture/
+- engineering/
+- runtime/
+
+### Governance Work
+
+Load:
+
+- governance/
+- runtime/
+
+### Runtime Maintenance
+
+Load:
+
+- runtime/
+- governance/

package/runtime/plans/_template.md

@@ -0,0 +1,81 @@
+# Plan: <FEATURE_NAME>
+
+## Goal
+
+Describe the overall engineering goal.
+
+---
+
+## Related Spec
+
+-
+
+---
+
+## Related ADRs
+
+-
+
+---
+
+## Supersedes
+
+<!-- Optional. Only include if this plan replaces an earlier
+     plan (e.g. after scope expansion or SUPERSEDED status on
+     the prior). Otherwise delete this section entirely. -->
+
+-
+
+---
+
+## Strategy
+
+Describe the implementation strategy.
+
+---
+
+## Task Graph
+
+### Task 1
+
+- Goal:
+- Dependencies:
+- Risk:
+
+### Task 2
+
+- Goal:
+- Dependencies:
+- Risk:
+
+### Task 3
+
+- Goal:
+- Dependencies:
+- Risk:
+
+---
+
+## Execution Order
+
+1.
+2.
+3.
+
+---
+
+## Verification Strategy
+
+-
+
+---
+
+## Rollback Strategy
+
+-
+
+---
+
+## Status
+
+PLANNED | IN_PROGRESS | DONE

package/runtime/prds/_template.md

@@ -0,0 +1,73 @@
+# PRD: <Feature Name>
+
+## Status
+
+DRAFT
+<!-- Allowed: DRAFT | APPROVED | REJECTED | SUPERSEDED.
+     PRDs follow the same lifecycle as specs but answer
+     "what & why," not "how." Engineering details (architecture,
+     data flow, code contracts) belong in the downstream spec. -->
+
+## Problem
+
+<!-- One paragraph. What user-facing or business problem is
+     being solved? What evidence makes this problem real
+     (data, support tickets, user quotes, missed opportunities)? -->
+
+## Target Users
+
+<!-- Who feels this problem, how often, in what context?
+     Be specific — "developers" is too broad; "first-time kit
+     consumers running `init` in an unfamiliar repo" is useful. -->
+
+-
+
+## Success Metrics
+
+<!-- Observable signals that the PRD has been satisfied
+     POST-SHIP. Not "the code compiles" — actual product-level
+     outcomes. Quantitative when possible; qualitative when not.
+     Examples: "time-to-first-spec drops from 2h to 15min",
+     "60% of v0.5 consumers run `npm publish` within 7 days of
+     adopting," "operator no longer hand-edits CLAUDE.md after
+     init." -->
+
+-
+
+## User Stories
+
+<!-- At least two. Format: "As a <role>, I want <capability>,
+     so that <outcome>." Stories drive the spec's Requirements
+     downstream — write them tight enough to test against. -->
+
+- As a , I want , so that .
+- As a , I want , so that .
+
+## Out of Scope
+
+<!-- Explicit non-goals. What this PRD will NOT cover, and why.
+     Items here often become future PRDs. -->
+
+-
+
+## Open Questions
+
+<!-- Decisions blocking sign-off. Each entry should name the
+     decider and the deadline (or "TBD"). Move resolved entries
+     into Stakeholders or strike them. -->
+
+-
+
+## Stakeholders
+
+- **Owner**:
+- **Reviewer(s)**:
+- **Consumer(s) of the output**:
+
+## Downstream Spec
+
+<!-- Once a spec is written against this PRD, reference it here
+     by path. The spec should reciprocally cite this PRD in §1
+     Goal. -->
+
+`.ai/project/specs/YYYY-MM-DD-<slug>/spec.md` (pending)

package/runtime/reviews/_template.md

@@ -0,0 +1,37 @@
+# Review: <Feature Name>
+
+## Summary
+
+
+
+## Verification
+
+<!-- What was verified? Typical contents:
+  - `npm run verify` result
+  - gate scripts from the spec's §5 (Acceptance Criteria)
+  - runtime-scoped preflight hook PASS/FAIL notes if §2 Scope
+    touched .ai/runtime/**
+-->
+
+## Acceptance Criteria
+
+<!-- Restate the spec's §5 Acceptance Criteria as a checklist
+     and mark each item with [x] (pass) or [ ] (fail). -->
+
+- [ ]
+
+## Blocking Issues
+
+None.
+
+## Non-blocking Issues
+
+None.
+
+## Suggested Fixes
+
+None.
+
+## Verdict
+
+Approved.

package/runtime/rules/README.md

@@ -0,0 +1,101 @@
+# Runtime Rules
+
+This directory hosts language- and scope-scoped rules. Each rule is
+a single `RULE.md` describing one always-on convention an agent
+should follow when touching code in scope.
+
+## Rules vs Skills
+
+| | Skill | Rule |
+| --- | --- | --- |
+| Trigger | Task type (Express endpoint, Drizzle migration) | Language / file scope (`.ts`, `.sql`) |
+| Loaded when | The current task matches the skill's purpose | The current task touches a file in scope |
+| Example | "How to add an Express endpoint" | "Use `interface` for exported object types" |
+
+If a guideline is task-conditional, it belongs in `skills/`. If it
+applies to all code in a language, it belongs in `rules/`.
+
+## Directory layout
+
+```txt
+.ai/runtime/rules/
+├── _template/
+│   └── RULE.md                       # template — copy from here
+├── <language>/                       # e.g. typescript, sql, python
+│   ├── README.md                     # index of rules for this language
+│   └── <topic>.md                    # one rule per file
+└── <scope>/                          # non-language scopes (e.g. http-api)
+    └── <topic>.md
+```
+
+Naming:
+
+- `<language>` and `<scope>` use lowercase kebab-case.
+- `<topic>` is a short noun phrase (`types.md`, `exports.md`,
+  `error-handling.md`).
+- One rule per file. If a topic has multiple sub-rules, split into
+  multiple files; do not stuff a single file.
+
+## When to create a rule
+
+A new rule is worth authoring when:
+
+- a review repeatedly catches the same violation across 2+ PRs, OR
+- a new language / framework is adopted and its idioms need
+  capturing, OR
+- a Biome rule does not encode a convention the project wants
+  enforced (semantic vs syntactic).
+
+Do NOT create a rule for:
+
+- something Biome already enforces (cite the Biome rule in the
+  config instead — keep the source of truth in `biome.json`),
+- a project-specific convention tied to this codebase only (those
+  belong in `.ai/project/memory/engineering/conventions.md`),
+- a one-off architectural preference (those belong in
+  `.ai/runtime/memory/architecture/principles.md` or in an ADR).
+
+## How rules get loaded
+
+Two loading paths, mirroring the skills system:
+
+1. **Workflow file** — `.ai/runtime/workflows/feature-development.md`
+   tells executors to load language rules matching modified files.
+   Strongest.
+2. **Context-loading rule** —
+   `.ai/runtime/memory/runtime/context-loading.md` lists language
+   rules under Feature Implementation. Weakest.
+
+A spec whose work touches code in a rule's scope should let the
+executor agent discover the rule automatically via path 1 or 2. No
+explicit reference required in §2 Scope unless the spec ALSO
+authors or modifies the rule itself.
+
+## Severity convention
+
+- **MUST** — violation blocks merge. Reviewer rejects.
+- **SHOULD** — strong default. Requires explicit justification in
+  the PR description / review file to deviate.
+- **MAY** — preference. Apply when convenient; document in the
+  review file when applied.
+
+## Authoring a new rule — the workflow
+
+1. **Open a spec** under `.ai/project/specs/YYYY-MM-DD-<name>/` whose
+   §2 Scope lists the new rule's path. Runtime-scoped governance
+   per `SAFETY.md` § Runtime Tree Protection.
+2. **Copy the template**: `cp .ai/runtime/rules/_template/RULE.md
+   .ai/runtime/rules/<language>/<topic>.md`. Create parent dirs.
+3. **Fill in template** sections. Cite a concrete "why" with at
+   least one incident or anti-pattern.
+4. **Register** by adding a line to `INDEX.md`'s `## Rules`
+   section listing the new rule + its severity.
+5. **Verify**: `npm run verify`.
+6. **Review**: standard review file under
+   `.ai/project/reviews/`.
+
+## Modifying an existing rule
+
+Same as authoring. If severity changes (e.g. SHOULD → MUST), the
+spec must list which existing code if any needs to be brought into
+compliance and budget for that work.

package/runtime/rules/_template/RULE.md

@@ -0,0 +1,75 @@
+# <Rule Name>
+
+## Severity
+
+MUST | SHOULD | MAY
+<!-- MUST = lint-level violation; review must reject.
+     SHOULD = strong default; require justification to deviate.
+     MAY = preference; document when applied. -->
+
+## When this rule applies
+
+- Language: `<language>` (e.g. TypeScript, SQL, Python).
+- File scope: `<glob>` (e.g. `src/**/*.ts`, `**/*.sql`).
+- Trigger: any time a task modifies a file matching the scope.
+
+Unlike skills, rules are NOT task-conditional — if a task touches a
+file in scope, the rule applies.
+
+---
+
+## Rule
+
+State the rule in one sentence. Imperative form.
+
+Example: "Use `interface` for object types that are part of a
+module's exported surface; use `type` for unions, intersections, or
+type-level computation."
+
+---
+
+## Why
+
+Why this rule exists. Cite a concrete failure mode or prior incident
+where ignoring the rule would have caused a problem. Without a
+documented "why", the rule has no defense when a future contributor
+challenges it.
+
+---
+
+## Examples
+
+### Compliant
+
+```ts
+// example of code that follows the rule
+```
+
+### Violating
+
+```ts
+// example of code that violates the rule
+```
+
+State briefly what's wrong with the violating example.
+
+---
+
+## Detection
+
+How a reviewer (human or agent) catches a violation:
+
+- Biome rule: `<rule-name>` (if applicable)
+- grep / AST pattern (if no lint encoding exists)
+- Manual: "reviewer reads diff and flags"
+
+If the rule is fully mechanically enforced by Biome, note that and
+keep this file as the human-readable rationale.
+
+---
+
+## Exceptions
+
+(Optional.) Situations where the rule should not apply, with
+justification. Each exception must be reproducible — vague "edge
+cases may exist" is not an exception.

package/runtime/skills/README.md

@@ -0,0 +1,96 @@
+# Runtime Skills
+
+This directory hosts reusable implementation skills. Each skill is a
+single `SKILL.md` documenting the rules an agent should follow when
+implementing a specific kind of work.
+
+## Directory layout
+
+```txt
+.ai/runtime/skills/
+├── _template/
+│   └── SKILL.md                          # template — copy from here
+├── <stack>/                              # tech-stack-scoped
+│   └── <skill-name>/
+│       └── SKILL.md
+└── <domain>/                             # domain-scoped (when stack-agnostic)
+    └── <skill-name>/
+        └── SKILL.md
+```
+
+Naming:
+
+- `<stack>` examples: `node-express`, `python-fastapi`, `react`,
+  `drizzle`. Use lowercase kebab-case.
+- `<domain>` examples: `security`, `migrations`, `observability`.
+- `<skill-name>` is a short noun phrase, lowercase kebab-case
+  (`express-endpoint`, `auth-token-rotation`).
+
+## When to create a skill
+
+A new skill is worth authoring when ANY of:
+
+- the same pattern has appeared in 3+ specs and would benefit from
+  consolidation,
+- a new tech stack is being adopted and its conventions differ from
+  existing skills,
+- a single complex pattern (e.g. atomic refresh-token rotation) is
+  spec-relevant across multiple specs.
+
+Do NOT create a skill for:
+
+- a one-off implementation detail,
+- a project-specific convention (those belong in
+  `.ai/project/memory/`),
+- a pure documentation pointer (a link in `INDEX.md` is enough).
+
+## How skills get loaded
+
+There are three loading paths, in decreasing order of strength:
+
+1. **Workflow file** — `.ai/runtime/workflows/feature-development.md`
+   tells executors to load "relevant skills". Strongest: the executor
+   agent decides which skill is relevant.
+2. **Context-loading rule** — `.ai/runtime/memory/runtime/context-loading.md`
+   lists "related skills" under "Feature Implementation". Weaker:
+   relies on the agent reading the rule and recognizing the match.
+3. **Frontmatter signals (declarative)** — the skill's YAML
+   frontmatter (`priority` / `pathPatterns` / `bashPatterns` /
+   `promptSignals`) is read by the agent during context-loading.
+   No runtime tooling reads or enforces it; it exists to help the
+   agent judge relevance. Weakest of the three paths.
+
+A spec whose work falls under an existing skill should reference the
+skill in its §2 Scope, so reviewers can confirm the executor loaded
+the right rules.
+
+## Authoring a new skill — the workflow
+
+1. **Open a spec** under `.ai/project/specs/YYYY-MM-DD-<name>/` whose
+   §2 Scope lists the new skill's path (this is a runtime-scoped
+   governance change per `SAFETY.md` § Runtime Tree Protection).
+2. **Copy the template**: `cp .ai/runtime/skills/_template/SKILL.md
+   .ai/runtime/skills/<stack>/<skill-name>/SKILL.md`. Make the
+   target directories first.
+3. **Fill in the frontmatter and the body sections.** Remove any
+   optional body sections that don't apply. Pick a `priority`
+   proportional to how stack-specific the trigger is. Frontmatter
+   fields are declarative (see "How skills get loaded" path 3) —
+   they describe when the skill applies; they do not auto-load
+   anything.
+4. **Register the skill** by adding a bullet to `INDEX.md`'s
+   `## Skills` section.
+5. **Add tests if applicable** — if the skill makes assertions that
+   can be checked statically (e.g. "all routes return JSON"),
+   consider adding a check script under `scripts/`.
+6. **Verify**: `npm run verify` plus any skill-specific assertions.
+7. **Review**: standard review file at
+   `.ai/project/reviews/YYYY-MM-DD-<name>-review.md`.
+
+## Modifying an existing skill
+
+Same as authoring: a runtime-scoped spec, with §2 Scope listing the
+modified SKILL.md path. If the modification changes how the skill is
+applied to existing code (not just clarifying language), include in
+the spec a note about whether existing code following the old skill
+needs updating.

package/runtime/skills/_template/SKILL.md

@@ -0,0 +1,61 @@
+<!--
+  Skill template. Copy this file to
+  `.ai/runtime/skills/<stack-or-domain>/<skill-name>/SKILL.md` and
+  fill it in.
+
+  The YAML frontmatter below is DECLARATIVE: no runtime tool reads or
+  enforces it. Agents read it during context-loading to judge whether
+  this skill applies. See `.ai/runtime/skills/README.md` § "How
+  skills get loaded" for the three loading paths.
+-->
+---
+name: <skill-name-kebab-case>
+description: <one sentence: when this skill applies and what it produces>
+metadata:
+  priority: <1-10, higher = stronger trigger>
+  pathPatterns:
+    - "<glob: e.g. src/**/*.ts>"
+  bashPatterns:
+    - "<regex: e.g. \\bnpm\\s+run\\s+build\\b>"
+  promptSignals:
+    phrases:
+      - "<exact phrase the user is likely to say>"
+    anyOf:
+      - "<keyword>"
+    minScore: <integer, e.g. 6>
+---
+
+# <Skill Name>
+
+<One paragraph describing what the agent should do when this skill is loaded.>
+
+## 目标
+
+- <deliverable 1>
+- <deliverable 2>
+
+## 输入 / 输出
+
+- **输入**：<source materials — files, user description, contracts>
+- **输出**：<destination — file path convention or report shape>
+
+## 工作方式
+
+1. <step 1>
+2. <step 2>
+3. <step 3>
+
+## 推荐输出结构
+
+```md
+<scaffold for the produced artifact>
+```
+
+## 约束
+
+- <constraint 1>
+- <constraint 2>
+
+## 完成标准
+
+<what "done" looks like — checkable criteria>

package/runtime/specs/_template/spec.md

@@ -0,0 +1,50 @@
+# Feature Spec: <Feature Name>
+
+## Status
+
+DRAFT
+<!-- Allowed: DRAFT | APPROVED | REJECTED | SUPERSEDED.
+     See .ai/runtime/workflows/feature-development.md for lifecycle rules. -->
+
+## Goal
+
+Describe the user or engineering outcome.
+
+## Scope
+
+<!-- If any in-scope path is under .ai/runtime/**, this is a
+     runtime-scoped governance change. Flag it explicitly in
+     "Includes:" and follow .ai/runtime/SAFETY.md § Runtime Tree
+     Protection. -->
+
+Includes:
+
+-
+
+Excludes:
+
+-
+
+## Requirements
+
+-
+
+## Acceptance Criteria
+
+-
+
+## Test Checklist
+
+-
+
+## Verification Commands
+
+```bash
+npm run verify
+```
+
+## Rollback Plan
+
+1.
+2.
+3.