kiro-pai-starter

Drop the PAI ISC (Ideal State Criteria) discipline into AWS Kiro IDE globally — five doctrine markdown files in ~/.kiro/steering/ so every Kiro session everywhere inherits the same articulate-the-ideal-state, atomic-criteria, live-probe-verification workflow.

What this is

A bare-minimum port of the PAI ISA + 7-phase discipline to Kiro. Five always-on steering files + one ISA template:

File	Says
steering/seven-phases.md	The seven phases: OBSERVE → THINK → PLAN → BUILD → EXECUTE → VERIFY → LEARN, what each does, the phase-transition contract
steering/isa-format.md	What an ISA is, the twelve fixed sections in order, frontmatter contract, ID-stability rule, two ISA homes
steering/isc-quality-gate.md	The granularity rule ("one binary tool probe per ISC"), the Splitting Test, Anti: and Antecedent: prefix conventions
steering/tier-gates.md	Effort tiers E1–E5 and which ISA sections are required at each
steering/verification-doctrine.md	"Should work" is not evidence — the probe-by-artifact-type table, the re-read check, the inline-verification mandate
steering/learning-capture.md	(v0.2.0) Learning Router doctrine — when LEARN writes a memo, the five memo types, filename + frontmatter contract, duplicate-check rule, SKIP-by-default disposition
steering/memos/	(v0.2.0) Where individual memos accrete over time (one file per learning, each its own steering file with inclusion: auto or always)
templates/ISA.template.md	Twelve-section ISA skeleton with comment placeholders
templates/memo.template.md	(v0.2.0) Memo skeleton — frontmatter + Why: / How to apply: / Related sections

That's it. No hooks, no MCP server, no overlay machinery.

What this is NOT

Explicitly out of scope at this floor:

• No invented #hashtag invocation patterns (no #scaffold-isa, #check-isa, etc.) — the always-on doctrine is enough; the agent reads it on every prompt and does the right thing when asked in plain English.
• No per-workspace memory directory scaffolding — the agent writes ISAs into whatever path the user names; nothing needs pre-creating.
• No per-ISC git checkpoint hook — Kiro hooks are UI-managed; not worth the friction at this floor.
• No MCP server, no reflection capture, no satisfaction ratings, no cross-session memo system, no mode classifier, no LifeOS/TELOS personal layer. All of these are upgrades that can be added later without touching the bare-minimum files.

Install (global)

This is the recommended path — installs the doctrine into your home directory's Kiro config so every Kiro session in every workspace inherits it.

git clone https://github.com/sjramblings/kiro-pai-starter /tmp/kps
mkdir -p ~/.kiro/steering/memos ~/.kiro/templates
cp /tmp/kps/steering/*.md ~/.kiro/steering/
cp /tmp/kps/templates/*.md ~/.kiro/templates/

# Confirm
ls ~/.kiro/steering/*.md        # expect 6 files (5 doctrine + learning-capture)
ls -d ~/.kiro/steering/memos    # exists (empty; memos accrete here over time)
ls ~/.kiro/templates/*.md       # expect 2 files (ISA + memo)

Restart your Kiro session (or just open a new one) and the doctrine is active. No restart needed for the next workspace — global steering loads automatically.

Install (per-workspace)

If you want to override or extend per project, drop the steering files into <project>/.kiro/steering/ instead. Per Kiro's steering docs, workspace steering wins on conflict with global.

mkdir -p <project>/.kiro/steering <project>/.kiro/templates
cp /tmp/kps/steering/*.md <project>/.kiro/steering/
cp /tmp/kps/templates/*.md <project>/.kiro/templates/

How to use after installing

In any Kiro session:

"Scaffold an ISA for adding S3 lifecycle rules at E3."

The agent now has all the doctrine in context (always-on steering loaded automatically). It copies ~/.kiro/templates/ISA.template.md to the right location, fills the E3-required sections (Problem, Vision, Out of Scope, Constraints, Goal, Criteria, Features, Test Strategy), applies the Splitting Test to the ISCs, and reports.

"Check the completeness of this ISA at tier E3."

The agent reads the ISA, scores it against tier-gates.md, reports missing required sections.

"Append a Changelog entry — we conjectured X, got refuted by Y..."

The agent appends a four-piece conjecture/refutation/learning entry in the canonical shape, refusing partial entries per isa-format.md.

No special invocation syntax. Plain English. The doctrine is in context.

Cross-session learning (v0.2.0)

The agent remembers across sessions by writing memo files into its own steering directory. Each memo is a markdown file with YAML frontmatter — inclusion: always for cross-cutting preferences, inclusion: auto for topical knowledge. When inclusion: auto is set, Kiro's native loader auto-loads the memo whenever the user's prompt matches the memo's description: field — so prior learnings show up in context exactly when they're relevant, without any INDEX file to curate.

Five memo types

Type	What it captures	Default inclusion:
feedback	Cross-cutting behavioral preferences and user corrections	always
gotcha	A specific trap with a specific fix	auto
project	Per-project state, decisions, deadlines	auto
setup	Environment, configuration, credential knowledge	auto
reference	A pointer to an external resource	auto

How a memo gets written

At the LEARN phase of any work, the agent applies the Learning Router doctrine in steering/learning-capture.md:

1. Default disposition is SKIP — most LEARN phases produce nothing worth keeping. A memo is only worth writing when the lesson generalizes to future tasks.
2. If a candidate IS worth keeping, classify the type (feedback / gotcha / project / setup / reference), pick inclusion: mode, grep ~/.kiro/steering/memos/ for duplicates.
3. Write the new file to ~/.kiro/steering/memos/{type}_{kebab-slug}.md with the frontmatter contract + the three-section body (paragraph + **Why:** + **How to apply:** + optional ## Related wikilinks).
4. Next session: Kiro's native loader picks the memo up automatically when its description: matches the user's prompt.

You can also invoke this explicitly in any session: "any memo worth capturing from this?" — the agent will reflect and either write the file or honestly answer no.

The loop

New session opens
   │
   ▼
Kiro loads always-on steering + any auto memos whose description: matches early conversation
   │
   ▼
Agent has prior learnings in context BEFORE doing any work
   │
   ▼
Work runs through the 7 phases (v0.1.0 doctrine)
   │
   ▼
LEARN: agent classifies candidates, writes new memo files per learning-capture.md
   │
   ▼
Next session opens with the EXPANDED memo set in scope ──> loop

No hooks, no scripts, no INDEX file. Doctrine + Kiro's native loader + markdown in the right place is the whole machine.

Verification — has the install landed?

ls ~/.kiro/steering/*.md | wc -l                              # expect 6 (5 v0.1.0 doctrine + learning-capture)
head -2 ~/.kiro/steering/*.md | grep -c "inclusion: always"   # expect 6
test -d ~/.kiro/steering/memos && echo "memos dir ok"         # expect "memos dir ok"
ls ~/.kiro/templates/*.md | wc -l                             # expect 2 (ISA + memo templates)
grep -c '^## ' ~/.kiro/templates/ISA.template.md              # expect 12 section headers
grep -q '\*\*Why:\*\*' ~/.kiro/templates/memo.template.md && echo "memo template ok"

Then in a Kiro session, ask the agent to scaffold an ISA. If it produces a 12-section file with frontmatter and doesn't fall back to Kiro's native spec triplet (requirements.md / design.md / tasks.md), the doctrine is live. To verify cross-session learning, run a small piece of work and ask "any memo worth capturing from this?" — the agent should classify, pick inclusion: mode, and write a new file to ~/.kiro/steering/memos/.

Where this came from

Daniel Miessler's PAI (Personal AI Infrastructure) — a comprehensive personal AI framework built around the ISA + 7-phase Algorithm + ISC discipline. The full PAI system carries far more than what's in this repo: a multi-tier memory pipeline (WORK → LEARNING → KNOWLEDGE), session reflection capture, satisfaction ratings, a Pulse dashboard, voice notifications, a closed-enumeration thinking-capability vocabulary, mode classification, an Interview workflow for adaptive ISA completion, cross-vendor audit gates, and a LifeOS personal layer.

This repo ports only the parts that translate cleanly to Kiro's always-on steering surface — the discipline, not the machinery.

Roadmap (explicitly NOT in this version)

Version	Adds	When to consider
v0.2.0	Shipped. Cross-session learning — memos as steering files with inclusion: auto, learning-capture.md Learning Router doctrine, memo template. See "Cross-session learning" section above.	Already in this release
v0.3.0	Per-workspace ISC checkpoint hook — shell script + README with screenshot-grade Command Palette setup instructions	When you want auto-commits on each ISC [ ]→[x] flip
v0.4.0	MCP server (kiro-pai-mcp) exposing typed scaffold_isa / check_completeness / append_isa tools registered in ~/.kiro/settings/mcp.json	When the agent demonstrates drift on canonical shapes (e.g., partial Changelog entries) in real use
v0.5.0	reflections.jsonl appender via post-prompt hook capturing per-session retrospection (distinct from memos — volume signals, not durable knowledge)	When you want to mine your own sessions for patterns

Each upgrade lands additively without touching the bare-minimum files.

License

MIT. See LICENSE.