git:20260805.e705c08 to git:20260825.36a5f1a
2 added, 0 removed. Audit A to A.
# DOX — packages/authoring-toolkit
Files in this directory. One row per source file.
| File | Purpose |
|------|---------|
| `.pi/skills/faq-mine/SKILL.md` | Skill (v2.0): mine `docs/faq.md` from docs (README.md + `docs/*.md`) AND pi-hermes memory stores (runtime problems). Dispatches @fast subagents per source, dedupes against existing FAQ, merges in caveman style. → see `.pi/skills/faq-mine/SKILL.md.AGENTS.md` |
| `.pi/skills/session-to-guideline/SKILL.md` | Skill: turn a session JSONL into a reusable playbook. Deterministic extract (`.pi/skills/session-to-guideline/scripts/extract_session.ts`) → facts sheet → judgment synthesis. Facts sheet now emits `ISO week bucket`, a deterministic `Premium candidate` flag (skill/memory created ∨ ≥5 user prompts ∨ ≥~10K-tok sheet), a deterministic `Session type` (development/planning/research/documentation/other from code-file/spec-file/search signals), and — only when the session touched `openspec/changes/<name>/` — an `OpenSpec changes` list + a `## Why` `Proposal excerpt`. Stories write to WEEKLY folders `Prompt stories/<YYYY>/W<WW>/<Topic>.md` with YAML frontmatter (session, week, type, model, premium, premium_reason, upgrade_status, and openspec_changes/proposal_excerpt when a proposal is attached). `list_sessions.ts`/`extract_session.ts` resolve a `--cwd` to the project root + every `.worktrees/*` worktree by default (worktree rows tagged `[wt:<name>]`; `--no-worktrees` for root-only). Budget-model (`@fast`/`@compact`) premium stories self-queue into `Prompt stories/_premium-queue.md` for a later `@research`/Opus upgrade pass. See change: weekly structure + premium-queue. |
+ | `.pi/skills/session-to-guideline/references/guideline-template.md` | "How we did it" playbook template emitted by session-to-guideline. Frontmatter: session, week (YYYY/Www), type (development/planning/research/documentation/other), model, premium, premium_reason, upgrade_status, openspec_changes + proposal_excerpt (only when facts sheet has OpenSpec changes). 8 sections: Goal, TL;DR playbook, collaboration phases, Prompts that worked, Steering & corrections guardrail table, Skills/tools/memory created, Pitfalls & dead ends, Reproduce-it-faster checklist. |
+ | `.pi/skills/skill-creator/SKILL.md` | Guide for creating effective skills. Anatomy: SKILL.md (frontmatter name+description only) + scripts/references/assets; progressive disclosure (metadata → body on trigger → resources as needed). Degrees of freedom: high/medium/low. Description = primary trigger, when-to-use in description not body; quote value containing colon-space (unquoted → loader silently drops skill, "Nested mappings are not allowed"). Scripts: init_skill.py <name> --path (scaffold), package_skill.py (validate → .skill zip). Test skill-frontmatter.test.mjs. See change: fix-skill-frontmatter-yaml. |
| `.pi/skills/skill-to-subagent/SKILL.md` | Portable procedure: convert a pi skill into an isolated subagent + wire into a pipeline. Discriminator (coherence-critical→inline skill; read/write-light+distilled→subagent) + fitness rubric. Bridge agent .md template (role-alias model, inherit_context, least-privilege tools, ≤2KB output contract). Model-by-function routing. Wiring = spawn-checkpoint table (pi has no auto-delegation). Pitfalls: YAML ": " trap silently drops agent, compression-drop, fresh ResourceLoader, telephone game. Tech-stack independent, pi-platform-specific. Repo-authored (MIT). |
| `README.md` | Package overview. General-purpose authoring skills for pi sessions. Pure-skill package (`package.json` manifest only, no `extension.ts`). Skills load by NL trigger: `skill-creator` (author/update a skill) and `session-to-guideline` (turn session JSONL into reusable playbook). Scripts run via `npx tsx scripts/…`, no build step. |