@createsomething/pi-policy-os 0.0.0-bootstrap

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+- Initial public release of the Policy OS extension, skills, and prompt templates for Pi.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Create Something
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @createsomething/pi-policy-os
+
+**Policy OS starter** for [Pi](https://pi.dev) coding agents — governed AI execution with quality gates, policy auditing, and the Subtractive Triad review methodology.
+
+## Install
+
+```bash
+pi install npm:@createsomething/pi-policy-os
+```
+
+Source price: **$0 under the MIT License**. Managed CREATE SOMETHING Control is a separate service, available from $900/month.
+
+## What You Get
+
+### Extension
+
+A lightweight quality gate extension that:
+
+- Warns when code files lack basic quality signals (missing types, untested exports)
+- Provides a `/policy-check` command to audit any codebase against Policy OS patterns
+- Shows governance status in the Pi footer
+
+### Skills
+
+- `/skill:policy-os-starter` — What Policy OS is, how contract bundles work, the MCP-First Thesis
+- `/skill:debug-feedback-loop` — Repro-first debugging for bugs, failing checks, and performance regressions
+- `/skill:intent-mapping` — Decision, scope, validation, and handoff capture before ambiguous or long-running work
+- `/skill:tdd-vertical-slice` — Test-first vertical-slice development through public interfaces
+
+### Prompt Templates
+
+- `/policy-audit` — Audit a codebase for governance gaps (missing tests, untyped exports, policy artifacts)
+- `/subtractive-review` — Apply the Subtractive Triad as code review methodology (DRY → Rams → Heidegger)
+
+## What Is Policy OS?
+
+Policy OS is CREATE SOMETHING's governed execution platform:
+
+1. **MCP servers establish trust** — controlled, permissioned access to your tools
+2. **Skills provide capabilities** — reusable, portable across agent platforms
+3. **Agents produce outcomes** — with approval gates, escalation policies, and quality controls
+
+**The MCP-First Thesis**: The entry point to automation is connectivity, not intelligence. MCP consumption is commoditized. MCP creation is not.
+
+## Go Further
+
+- [CREATE SOMETHING](https://createsomething.agency) — Custom MCP development and Policy OS delivery
+- [Three-Tier Framework](https://www.npmjs.com/package/@createsomething/pi-three-tier-framework) — The architectural model
+- [Policy OS paper](https://createsomething.io/papers/policy-os-development-infrastructure)

package/extensions/policy-os-starter.ts

@@ -0,0 +1,115 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+function run(cmd: string, cwd?: string): string {
+  try {
+    return execSync(cmd, { cwd: cwd ?? process.cwd(), encoding: "utf-8", timeout: 30_000, stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch { return ""; }
+}
+
+export default function (pi: ExtensionAPI) {
+
+  // Show governance status in footer
+  pi.on("session_start", async (_event, ctx) => {
+    const root = process.cwd();
+
+    // Quick governance signal scan
+    const signals: string[] = [];
+    if (fs.existsSync(path.join(root, ".husky"))) signals.push("hooks");
+    if (fs.existsSync(path.join(root, ".github/workflows"))) signals.push("CI");
+    if (fs.existsSync(path.join(root, "docs/policies"))) signals.push("policies");
+
+    const score = signals.length === 0 ? "ungoverned" : signals.join("+");
+    ctx.ui.setStatus("policy-os", `⚖️ ${score}`);
+  });
+
+  // /policy-check command
+  pi.registerCommand("policy-check", {
+    description: "Quick Policy OS governance check on this project",
+    handler: async (_args, ctx) => {
+      const root = process.cwd();
+      ctx.ui.setStatus("policy-os", "🔍 Checking…");
+
+      const checks: Array<{ name: string; pass: boolean; detail: string }> = [];
+
+      // 1. Pre-commit hooks
+      const hasHusky = fs.existsSync(path.join(root, ".husky"));
+      const hasLintStaged = fs.existsSync(path.join(root, ".lintstagedrc")) || fs.existsSync(path.join(root, "lint-staged.config.js"));
+      checks.push({
+        name: "Pre-commit hooks",
+        pass: hasHusky || hasLintStaged,
+        detail: hasHusky ? "Husky configured" : hasLintStaged ? "lint-staged configured" : "No pre-commit hooks found",
+      });
+
+      // 2. CI pipeline
+      const hasGHA = fs.existsSync(path.join(root, ".github/workflows"));
+      checks.push({
+        name: "CI pipeline",
+        pass: hasGHA,
+        detail: hasGHA ? "GitHub Actions found" : "No CI configuration found",
+      });
+
+      // 3. Type checking
+      const hasTsConfig = fs.existsSync(path.join(root, "tsconfig.json")) || fs.existsSync(path.join(root, "tsconfig.base.json"));
+      checks.push({
+        name: "TypeScript",
+        pass: hasTsConfig,
+        detail: hasTsConfig ? "TypeScript configured" : "No tsconfig found",
+      });
+
+      // 4. Agent context files
+      const hasAgentsMd = fs.existsSync(path.join(root, "AGENTS.md")) || fs.existsSync(path.join(root, "CLAUDE.md"));
+      checks.push({
+        name: "Agent context",
+        pass: hasAgentsMd,
+        detail: hasAgentsMd ? "AGENTS.md or CLAUDE.md found" : "No agent context file",
+      });
+
+      // 5. Policy artifacts
+      const hasPolicies = fs.existsSync(path.join(root, "docs/policies"));
+      const policyCount = hasPolicies ? run("ls docs/policies/v1/*.md 2>/dev/null | wc -l", root).trim() : "0";
+      checks.push({
+        name: "Policy artifacts",
+        pass: hasPolicies,
+        detail: hasPolicies ? `${policyCount} versioned policies` : "No policy directory",
+      });
+
+      // 6. Tests
+      const pkgJson = path.join(root, "package.json");
+      let hasTest = false;
+      if (fs.existsSync(pkgJson)) {
+        try { hasTest = !!JSON.parse(fs.readFileSync(pkgJson, "utf-8")).scripts?.test; } catch {}
+      }
+      checks.push({
+        name: "Test scripts",
+        pass: hasTest,
+        detail: hasTest ? "Root test script found" : "No test script in package.json",
+      });
+
+      // Build report
+      const passed = checks.filter((c) => c.pass).length;
+      const total = checks.length;
+      const score = Math.round((passed / total) * 100);
+
+      const lines = [
+        `## Policy OS Governance Check`,
+        ``,
+        `**Score: ${score}/100** (${passed}/${total} checks passing)`,
+        ``,
+        ...checks.map((c) => `${c.pass ? "✅" : "❌"} **${c.name}**: ${c.detail}`),
+        ``,
+        `### Recommended Tier`,
+        score >= 80 ? "→ **Policy OS Core** — strong governance foundation" :
+        score >= 50 ? "→ **Policy OS Trial** — governance gaps to address" :
+        "→ **MCP Audit** — needs governance foundation before Policy OS",
+        ``,
+        `Learn more: https://createsomething.agency`,
+      ];
+
+      ctx.ui.setStatus("policy-os", score >= 80 ? "✓ Governed" : `⚠️ ${score}/100`);
+      pi.sendUserMessage(lines.join("\n"), { deliverAs: "followUp" });
+    },
+  });
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@createsomething/pi-policy-os",
+  "version": "0.0.0-bootstrap",
+  "description": "Policy OS starter for Pi coding agents — governed AI execution with quality gates, policy checks, and the MCP-First Thesis. The entry point to CREATE SOMETHING's governed automation platform.",
+  "keywords": [
+    "pi-package",
+    "policy-os",
+    "governance",
+    "mcp",
+    "quality-gates",
+    "agent-systems"
+  ],
+  "author": "CREATE SOMETHING <hello@createsomething.agency>",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "skills",
+    "prompts",
+    "extensions",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/createsomethingtoday/create-something-monorepo.git",
+    "directory": "packages/pi-policy-os"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ],
+    "extensions": [
+      "./extensions"
+    ]
+  }
+}

package/prompts/policy-audit.md

@@ -0,0 +1,64 @@
+---
+description: Audit a codebase for Policy OS governance gaps
+argument-hint: "[path]"
+---
+
+Load the policy-os-starter skill, then audit `$@` for governance gaps.
+
+## Checks
+
+### 1. Quality Gate Coverage
+- Are there pre-commit hooks? (`husky`, `lint-staged`, `.husky/`)
+- Are there CI checks? (`.github/workflows/`, type check, lint, test)
+- Is there a design system enforced? (token compliance, component library)
+
+### 2. Agent Legibility
+- Does each package have a clear entry point?
+- Is there a boot command documented?
+- Is there a smoke/validation path?
+- Is there an escalation rule?
+
+### 3. Policy Artifacts
+- Are there versioned policy files? (`policies/`, `*.policy.*`)
+- Are approval gates defined?
+- Are escalation paths documented?
+
+### 4. Evidence Surface
+- Where is delivery evidence recorded?
+- Is there an issue tracker integration?
+- Are deploys traceable to issues?
+
+### 5. Subtractive Triad Compliance
+- **DRY**: Any obvious duplication across packages?
+- **Rams**: Any packages/files that don't earn their existence?
+- **Heidegger**: Any orphaned code that doesn't serve the whole?
+
+## Output
+
+```
+## Policy Audit: [path]
+
+### Governance Score: [0-100]
+
+### Quality Gates: [score]
+- ...
+
+### Agent Legibility: [score]
+- ...
+
+### Policy Artifacts: [score]
+- ...
+
+### Evidence Surface: [score]
+- ...
+
+### Recommendations (prioritized)
+1. ...
+2. ...
+3. ...
+
+### Policy OS Fit
+- Current tier: [MCP-only | Policy OS Trial | Policy OS Core]
+- Recommended tier: ...
+- Key gap: ...
+```

package/prompts/subtractive-review.md

@@ -0,0 +1,53 @@
+---
+description: Apply the Subtractive Triad as code review methodology (DRY → Rams → Heidegger)
+argument-hint: "[path or git diff]"
+---
+
+Load the policy-os-starter skill, then review `$@` through the Subtractive Triad lens.
+
+## Pass 1: DRY (Implementation)
+
+**Question**: "Have I built this before?"
+
+- Scan for code duplication within the diff
+- Check for patterns existing elsewhere in the codebase
+- Look for reinvented utilities
+- Identify copy-paste from other files
+
+## Pass 2: Rams (Artifact)
+
+**Question**: "Does this earn its existence?"
+
+Apply Rams' principles:
+1. Is it useful? Does it solve a real problem?
+2. Is it honest? Does it promise only what it delivers?
+3. Is it understandable? Is purpose self-evident?
+4. Is it unobtrusive? Does complexity recede?
+5. Is it as little as possible? Can anything be removed?
+
+## Pass 3: Heidegger (System)
+
+**Question**: "Does this serve the whole?"
+
+- Does the change strengthen system coherence?
+- Are there circular dependencies?
+- Are there orphaned files?
+- Does this automation enable dwelling or merely accelerate consumption? (Gestell check)
+- Are we adopting patterns because they're common, or because this work demands them? (Das Man check)
+
+## Output
+
+```
+# Subtractive Review
+
+## Summary
+Files: N | Added: +X | Removed: -Y
+
+## Pass 1: DRY — [findings]
+## Pass 2: Rams — [findings]
+## Pass 3: Heidegger — [findings]
+
+## Verdict: [✅ APPROVED | ⚠️ COMMENTS | ❌ CHANGES REQUESTED]
+```
+
+If no path given, review `git diff HEAD`.

package/skills/debug-feedback-loop/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: debug-feedback-loop
+description: Repro-first debugging for bugs, failing checks, and performance regressions. Use when something is broken, slow, flaky, or throwing and the next step needs evidence rather than a theory.
+---
+
+# Debug Feedback Loop
+
+Use this skill to keep debugging sessions evidence-led. The goal is one tight
+command that can prove the bug is present before changing code, then prove it is
+gone after the fix.
+
+This is a Policy OS execution loop:
+
+| Tier           | Debug question                                                                | Evidence                                                             |
+| -------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **Database**   | Is the source data, config, fixture, or external state correct and available? | fixture, API response, DB row, env binding, log excerpt              |
+| **Automation** | Did the code path, tool, worker, or job execute correctly?                    | test, CLI run, smoke, trace, workflow log                            |
+| **Judgment**   | Was the right policy, approval, route, or fallback applied?                   | policy artifact, Linear evidence, approval record, expected decision |
+
+Check tiers in that order. Lower-tier failures make higher-tier theories noisy.
+
+## Required Loop
+
+Do not start with a likely cause. Start by building a feedback loop.
+
+A valid loop is:
+
+- **Red-capable**: it drives the reported failure path and asserts the specific
+  symptom, not just "does not crash".
+- **Deterministic**: same verdict every run, or a known high reproduction rate
+  for flaky failures.
+- **Fast enough**: seconds when possible; narrow minutes when the real path is a
+  worker, browser, or CI workflow.
+- **Agent-runnable**: a command the agent can run without manual clicking unless
+  the task is explicitly human-in-the-loop.
+
+Preferred loop shapes:
+
+1. Package-local test or smoke.
+2. CLI command with a fixture and explicit expected output.
+3. HTTP `curl` or route smoke against a local or preview server.
+4. Browser automation for UI regressions.
+5. Captured trace replay, HAR replay, queue payload, or workflow log replay.
+6. Small throwaway harness when no public command reaches the path.
+
+For CREATE SOMETHING repos, prefer existing commands before inventing new ones:
+
+```bash
+pnpm exports <package> <symbol>
+pnpm --filter <package> test
+pnpm --filter <package> check
+pnpm check
+pnpm lint
+pnpm agent:solo-loop:check
+```
+
+Use Context7 for unstable third-party APIs. Use Ground before claiming duplicate
+code, dead exports, orphaned modules, or environment-boundary mistakes.
+
+## Workflow
+
+1. **Name the symptom**
+   - Quote or summarize the exact failure, error, wrong output, slow timing, or
+     user-visible behavior.
+   - Identify the owning truth surface: local command, package test, browser
+     route, deployed worker, Linear issue, GitHub check, Airtable/Admin state,
+     or another external source.
+
+2. **Build the loop**
+   - Produce one command or scripted check that can go red for this bug.
+   - If no loop is possible, stop and state what artifact is missing: access,
+     logs, fixture, HAR, trace, screen recording, or permission to add temporary
+     instrumentation.
+
+3. **Reproduce and minimize**
+   - Run the loop and capture the failing output.
+   - Remove inputs, config, fixtures, and steps one at a time until the smallest
+     load-bearing failure remains.
+
+4. **Rank hypotheses**
+   - Write 3 to 5 falsifiable hypotheses only after the loop exists.
+   - Each hypothesis must predict what observation or one-variable change would
+     confirm or falsify it.
+
+5. **Instrument narrowly**
+   - Probe one hypothesis at a time.
+   - Tag temporary logs with a unique prefix such as `[DEBUG-20260629-a]`.
+   - For performance work, measure before changing code.
+
+6. **Fix with a regression check**
+   - Add the smallest regression test or smoke at the correct public interface.
+   - If no correct interface exists, record that as an architecture finding and
+     keep the original loop as completion evidence.
+   - Apply the fix, rerun the regression check, then rerun the original loop.
+
+7. **Clean up and record evidence**
+   - Remove temporary logs and throwaway harnesses unless they became real tests.
+   - For tracked work, record commands, pass/fail results, branch or worktree,
+     deploy or smoke evidence, rollback note, and caveats in Linear.
+
+## Completion Bar
+
+Do not call the bug fixed until all of these are true:
+
+- Original loop now passes.
+- Regression check passes, or the lack of a correct test surface is documented.
+- Temporary instrumentation is removed.
+- The final explanation names the proven cause and the evidence that ruled out
+  the wrong theories.
+- Linear evidence is updated when the work is shared, delegated, production
+  bound, or needed for handoff.

package/skills/intent-mapping/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: intent-mapping
+description: Intent mapping for ambiguous, long-running, shared, or production-bound work. Use when the user wants to clarify a plan, scope a goal, prepare Linear work, or resolve decisions before implementation.
+---
+
+# Intent Mapping
+
+Use this skill to turn fuzzy intent into a durable execution packet before work
+starts. The goal is shared understanding, not a planning ceremony.
+
+Intent mapping is the CREATE SOMETHING adaptation of a relentless interview:
+ask one useful question, recommend the likely answer, then wait. Continue until
+the open decisions are resolved enough to choose the correct workflow lane.
+
+## Repo Rules
+
+- Read `AGENTS.md`, package-local `AGENTS.md`, relevant README files, and nearby
+  tests or docs before asking questions that the repo can answer.
+- Use Linear for shared, delegated, long-running, production-bound, or
+  evidence-bearing work.
+- Use `pnpm agent:solo-loop` for solo current-checkout exploration.
+- Use `pnpm agent:claim-worktree -- --issue CRE-123` for isolated
+  implementation work that needs a durable handoff.
+- Do not create Loom tasks, local issue files, GitHub issues, or a second
+  tracker for this workflow.
+
+## Question Loop
+
+Ask one question at a time. Multiple questions at once hide dependencies between
+decisions and make it harder for the user to correct the path.
+
+Each question must include:
+
+- the decision being resolved
+- your recommended answer
+- why that recommendation fits the repo, product, or workflow
+- what the answer will change about implementation, validation, or handoff
+
+If the answer can be discovered from the codebase, docs, Linear issue, browser
+state, logs, or another owning truth surface, inspect that source instead of
+asking the user.
+
+Prefer concrete choices over abstract discussion. Good questions ask for a
+decision that changes the work.
+
+## Map Mode
+
+Use map mode when one intent-mapping session reveals more decision work than a
+single agent session should hold, or when the work is shared, delegated,
+long-running, production-bound, or explicitly needs many grilling sessions.
+Map mode is the Linear-native way to orchestrate that breadth; do not install a
+second tracker or copy an external issue workflow wholesale.
+
+Stay out of map mode when the way is already clear enough to produce one Intent
+Packet. In that case, finish the packet and let the user correct it before
+implementation starts.
+
+When map mode is needed:
+
+1. Create or use one Linear issue as the map. Its body is an index, not the
+   source of every answer.
+2. Name the destination first. The destination fixes scope, non-goals, and stop
+   conditions.
+3. Use these map sections: `Destination`, `Notes`, `Decisions so far`, `Not yet
+specified`, and `Out of scope`.
+4. Create child or linked Linear issues only for questions that are sharp enough
+   to state now. Each issue should resolve one decision and fit in one agent
+   session.
+5. Put unclear future work in `Not yet specified` as fog, not as premature
+   tickets. Graduate fog into tickets only when the question becomes precise.
+6. Use Linear-native parent, relation, assignment, and blocking fields where
+   available. If a native relationship is unavailable, link the map and child
+   issues explicitly in their descriptions.
+7. Treat the frontier as the open, unblocked, unclaimed child issues. Claim one
+   frontier issue before working it.
+8. Never resolve more than one map ticket in a single session. Record the answer
+   on that ticket, close it, then append only a short pointer to the map's
+   `Decisions so far`.
+9. If a ticket turns out to sit beyond the destination, close it as out of scope
+   and link it from the map's `Out of scope` section instead of treating it as a
+   decision on the route.
+
+Ticket types are:
+
+- `Grilling`: human-in-the-loop decision work, one question at a time.
+- `Research`: agent-driven reading of docs, code, logs, or external sources.
+- `Prototype`: a cheap artifact created to make a decision concrete.
+- `Task`: manual or agent work that must happen before a decision can be made.
+
+Charting a map is one session of work. Stop after the map and first frontier are
+created; do not also start resolving tickets unless the user explicitly asks to
+continue and the next ticket has been claimed.
+
+## Tier Mapping
+
+Classify the work before recommending a lane:
+
+| Tier           | Intent question                                                 | Useful evidence                                      |
+| -------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
+| **Database**   | What state, resource, artifact, or source of truth must change? | schema, fixture, API response, config, policy doc    |
+| **Automation** | What execution path, tool, worker, route, or command must run?  | test, CLI, smoke, workflow log, browser proof        |
+| **Judgment**   | What policy, approval, fallback, or operator decision applies?  | Linear evidence, approval note, policy artifact, ADR |
+
+If the work crosses tiers, keep the tier ownership explicit in the packet.
+
+## Intent Packet
+
+Stop asking once you can produce this packet without guessing:
+
+```text
+Linear: <CRE-123, create one, or none>
+Lane: <solo-loop | claim-worktree | PR/promotion | research/no-edit>
+Tier: <Database | Automation | Judgment | mixed>
+Goal: <one concrete outcome>
+Decisions:
+- <decision and chosen answer>
+Non-goals:
+- <explicitly excluded work>
+Acceptance criteria:
+- <observable done condition>
+Verification:
+- <commands, smoke checks, browser checks, or external truth surfaces>
+Stop conditions:
+- <when to pause, ask, or escalate>
+Policy artifacts:
+- <AGENTS.md, policy docs, runbooks, issue links, approval requirements>
+Evidence target:
+- <Linear comment, PR body, deploy note, local summary, or none>
+```
+
+For Linear-tracked work, include the packet in the issue description or a Linear
+comment before implementation starts. For solo-loop work, include the packet in
+the starter prompt or first agent message.
+
+## Completion Bar
+
+Intent mapping is complete only when:
+
+- every open decision that affects implementation, validation, or handoff has a
+  chosen answer or an explicit stop condition
+- the correct lane is selected
+- the verification surface is named
+- production, deploy, merge, credential, and third-party mutation boundaries are
+  explicit
+- the user has had a chance to correct the packet before implementation begins

package/skills/policy-os-starter/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: policy-os-starter
+description: Policy OS product overview, contract bundles, the MCP-First Thesis, and the Subtractive Triad. Use when reasoning about governance, quality gates, or agent delivery patterns.
+---
+
+# Policy OS Starter
+
+The essential knowledge for working with CREATE SOMETHING's governed execution platform.
+
+## The MCP-First Thesis
+
+**The entry point to automation is connectivity, not intelligence.**
+
+The pattern from industry adoption:
+1. **MCP servers establish trust** (controlled, permissioned access)
+2. **Skills provide capabilities** (reusable, portable across platforms)
+3. **Agents produce outcomes** (the monetizable layer)
+
+**MCP consumption is commoditized. MCP creation is not.** — This is the moat.
+
+## Policy OS Definition
+
+Policy OS is the canonical paid CREATE SOMETHING package for governed AI execution. It combines:
+
+- Custom MCP connectivity
+- Agent and workflow behavior contracts
+- Policy artifacts and approval boundaries
+- Operator runbooks and golden-task regressions
+- Recurring review, tuning, and escalation operations
+
+## Service Tiers
+
+| Tier | Scope |
+|------|-------|
+| **MCP Audit** | Diagnose what MCPs to build |
+| **MCP-only** | Free discovery/compliance wedge |
+| **Policy OS Trial** | Time-limited paid trial |
+| **Policy OS Core** | Full governed execution |
+
+## Contract Bundle
+
+Every Policy OS engagement ships these artifacts:
+
+| Artifact | Purpose |
+|----------|---------|
+| `mcp_contract.yaml` | MCP connectivity scope and permissions |
+| `agent_contract.yaml` | Agent behavior boundaries and tool access |
+| `outcome_contract.md` | Expected outcomes and success metrics |
+| `golden_tasks.yaml` | Regression test tasks for quality assurance |
+| `runbook.md` | Operator procedures, escalation paths |
+
+## The Subtractive Triad
+
+The code review and decision-making methodology:
+
+| Level | Discipline | Question | Action |
+|-------|-----------|----------|--------|
+| **Implementation** | DRY | "Have I built this before?" | Unify |
+| **Artifact** | Rams | "Does this earn its existence?" | Remove |
+| **System** | Heidegger | "Does this serve the whole?" | Reconnect |
+
+Apply in order. Each level enables the next.
+
+## Quality Gate Patterns
+
+Policy OS governance translates to agent quality gates:
+
+| Gate | When | What |
+|------|------|------|
+| **Pre-execution** | Before tool calls | Block dangerous commands, enforce naming |
+| **Post-execution** | After writes/edits | Check design system compliance, import validity |
+| **Pre-completion** | Before agent finishes | Type check, lint, uncommitted changes |
+| **Evidence** | Session end | Record delivery evidence in issue tracker |
+
+## Applying Policy OS to Any Codebase
+
+Ask these questions to identify governance gaps:
+
+1. **What breaks today?** → Identifies quality gate needs
+2. **What actions need approval?** → Identifies judgment boundaries
+3. **What should never happen?** → Identifies bash guard rules
+4. **How do you verify correctness?** → Identifies pre-completion checks
+5. **Where is delivery evidence recorded?** → Identifies evidence surface

package/skills/tdd-vertical-slice/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: tdd-vertical-slice
+description: Test-first vertical-slice development for CREATE SOMETHING packages. Use when adding behavior or fixing bugs where a public interface test can drive the change.
+---
+
+# TDD Vertical Slice
+
+Use this skill when the work should be driven by one behavior at a time. The
+goal is not "write all tests first"; the goal is a tight red-green-refactor loop
+through the same public interface real callers use.
+
+## Policy
+
+This is a Policy OS quality loop:
+
+- **Database**: fixtures, records, bindings, resources, and policy artifacts are
+  explicit.
+- **Automation**: one test or smoke drives one executable behavior.
+- **Judgment**: acceptance criteria and approval boundaries stay visible.
+
+Do not create issue-tracker state from this skill. Use Linear only when the work
+is shared, delegated, long-running, production-bound, or needs durable evidence.
+
+## Before Writing Tests
+
+1. Read the nearest `AGENTS.md`, package README, and existing tests.
+2. Verify local package imports with `pnpm exports` before using
+   `@create-something/*` symbols.
+3. Use Context7 for unstable third-party APIs.
+4. Identify the public interface that should carry the behavior.
+5. Name the first observable behavior in user or operator language.
+
+Ask only when the public interface or acceptance behavior is ambiguous. For a
+narrow confirmed bug or implementation request, proceed with the smallest
+defensible behavior.
+
+## Loop
+
+Run one vertical slice at a time:
+
+1. **Red**: add one failing test or smoke for one behavior.
+2. **Green**: implement the smallest code path that passes it.
+3. **Refactor**: remove duplication and improve locality while tests stay green.
+4. **Repeat**: add the next behavior only after the previous slice is green.
+
+Never write a batch of speculative tests for imagined behavior. Tests should
+respond to the real interface and what the previous slice revealed.
+
+## Test Surface Rules
+
+Prefer tests that:
+
+- cross the same interface callers use
+- assert observable behavior rather than private structure
+- keep fixtures small and explicit
+- survive internal refactors
+- use real code paths unless an external boundary must be adapted
+
+Avoid tests that:
+
+- mock internal collaborators just to reach private functions
+- assert implementation shape instead of behavior
+- check a database or filesystem side effect while bypassing the owning
+  interface
+- require broad environment setup when a smaller public command can prove the
+  same behavior
+
+## Useful Commands
+
+```bash
+pnpm exports <package> <symbol>
+pnpm --filter <package> test
+pnpm --filter <package> check
+pnpm check
+pnpm lint
+git diff --check
+```
+
+For fresh worktrees, run `pnpm bootstrap:worktree` before commands that expect
+workspace binaries such as `pnpm exec tsc` or `pnpm exec tsx`.
+
+## Completion Bar
+
+The slice is complete only when:
+
+- the new behavior test or smoke passes
+- relevant package checks pass
+- no unrelated tests were weakened or deleted
+- imports and public exports are verified when changed
+- Linear evidence is updated when the work requires handoff, review, promotion,
+  rollback, or durable completion evidence