@aryaminus/controlkeel-opencode 0.3.1 → 0.3.2

package/.opencode/skills/align/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: align
+description: "Interview the user about their goal before any plan or code. Reach shared understanding of what, why, which layers, success criteria, and unknowns. Feed the result into plan-slice or ck_review_submit."
+when_to_use: "Activate at the very start of any new feature, fix, or project — before writing a PRD, submitting a plan, or touching any code. Also activate when a brief or Slack message arrives and the intent is not yet fully clear."
+argument-hint: "[goal description or raw brief]"
+license: Apache-2.0
+compatibility:
+  - codex
+  - claude-standalone
+  - claude-plugin
+  - copilot-plugin
+  - github-repo
+  - open-standard
+metadata:
+  author: controlkeel
+  version: "1.0"
+  category: planning
+  ck_mcp_tools:
+    - ck_context
+    - ck_goal
+    - ck_memory_record
+    - ck_memory_search
+---
+
+# Align Skill
+
+Reach a **shared design concept** with the user before any plan or code is written. The most expensive misalignment is the one caught after implementation — catch it here instead.
+
+## Protocol
+
+1. Call `ck_context` to load current session state, domain pack, and any prior goals or decisions already recorded.
+2. Call `ck_memory_search` with the user's stated goal to surface prior aligned work on the same area before asking redundant questions.
+3. Ask the user **one question at a time**. For each question, provide your recommended answer so the user can confirm, adjust, or replace it — never leave them staring at a blank.
+4. Work through the alignment tree in this order:
+
+   **What** — What is the exact outcome? What is explicitly out of scope?
+   **Why** — What problem does this solve? What is the success signal?
+   **Who** — Who uses the result? Which roles, systems, or integrations are affected?
+   **Layers** — Which system layers does this touch? (schema, services, APIs, UI, infra, third-party) Record each touched layer explicitly — this drives vertical slice decomposition later.
+   **Acceptance criteria** — What does "done" look like? What would a failing test catch?
+   **Edge cases** — What breaks if inputs are invalid, empty, or unexpected?
+   **Constraints** — Budget, timeline, tech stack limits, compliance requirements, or must-not-change areas.
+   **Unknowns** — What do you not know yet? What needs a spike or research before implementation starts?
+
+5. After each resolved decision, call `ck_memory_record` with type `decision` to persist it. Future agents resuming this work will recover these without asking again.
+6. When alignment is complete, call `ck_goal` (mode: `record`, horizon: `session`) to record the aligned goal with its acceptance criteria and touched layers.
+7. Tell the user the alignment is complete and recommend the next step:
+   - If the work is multi-layer and will need decomposition → activate `plan-slice`.
+   - If the work is a single small change that fits in one task → proceed to `ck_review_submit` (plan_phase: `narrowed_decision`).
+
+## Non-negotiable rules
+
+- Never skip alignment and go straight to planning or code, even for "small" tasks. A missed constraint at this stage compounds into blocked findings or rework later.
+- Do not produce a plan, PRD, or code during this skill. The output is a recorded goal and a set of decisions — nothing else.
+- If the user says "just do it," record what you know so far, note the unknowns explicitly, and move forward — but surface the open questions as warnings so they can surface as findings if they bite later.
+- Planning is always human-in-the-loop. The agent asks; the human decides. Never answer your own alignment questions and continue as if the human agreed.
+
+## What you produce
+
+At the end of this skill:
+- A `ck_goal` record with: objective, acceptance criteria, touched layers, known constraints, open unknowns.
+- One or more `ck_memory_record` entries (type: `decision`) for each resolved design choice.
+- A clear recommendation on whether to proceed to `plan-slice` or directly to `ck_review_submit`.
+
+## Additional resources
+
+- For the full governed workflow, see [references/workflow.md](references/workflow.md)

package/.opencode/skills/controlkeel-governance/SKILL.md

@@ -51,6 +51,10 @@ metadata:
 
 You are operating inside a **ControlKeel-governed session**. Start here whenever you need the base CK operating protocol.
 
+## Before new work
+
+For any new feature, fix, or project — before writing plans or code — use the `align` skill to reach shared understanding of the goal, layers, and acceptance criteria. Once aligned, use `plan-slice` to decompose the goal into vertical slices with explicit blocking relationships before any implementation begins. Planning is always human-in-the-loop; implementation of an approved slice can be AFK.
+
 ## Core loop
 
 1. Call `ck_context` at task start to load mission, risk, budget, proof, active findings, workspace context, context reacquisition, instruction hierarchy, and recent transcript state.
@@ -94,6 +98,8 @@ You are operating inside a **ControlKeel-governed session**. Start here whenever
 - `ck_deployment_advisor` — repo stack detection, CI/Docker generation, DNS/SSL guide
 - `ck_outcome_tracker` — record and review session outcomes/agent scores
 - `ck_skill_list`, `ck_skill_load` — specialized workflow activation
+- `align` skill — pre-work alignment interview before any plan or code
+- `plan-slice` skill — vertical slice decomposition with blocking relationships and autonomy labels
 
 ## Additional resources
 

package/.opencode/skills/handoff/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: handoff
+description: "Persist session state and hand off in-progress work to a background agent or delegated execution. Use when work outgrows the current session, context is near limit, or a task needs to continue unattended."
+when_to_use: "Activate when the user says 'hand off', 'delegate this', 'continue in background', 'pass this off', or when context pressure is high and significant work remains. Also activate when ck_route recommends a different agent for the remaining work."
+argument-hint: "[optional: specific task or remaining work to hand off]"
+license: Apache-2.0
+compatibility:
+  - codex
+  - claude-standalone
+  - claude-plugin
+  - copilot-plugin
+  - github-repo
+  - open-standard
+metadata:
+  author: controlkeel
+  version: "1.0"
+  category: execution
+  ck_mcp_tools:
+    - ck_context
+    - ck_memory_record
+    - ck_memory_search
+    - ck_route
+    - ck_delegate
+    - ck_goal
+---
+
+# Handoff Skill
+
+Transfer in-progress work to another agent or execution context with full state preservation, so work continues seamlessly after the current session ends or context runs out.
+
+## When to use this skill
+
+- Context window is approaching its limit and substantial work remains
+- The user wants work to continue unattended (background execution)
+- `ck_route` recommends a different agent or runtime for the remaining task
+- The user explicitly asks to delegate, hand off, or pass work to a background agent
+
+## Protocol
+
+1. Call `ck_context` to load current session state, open findings, active goal, and proof summary.
+
+2. Call `ck_memory_search` with the current task description to surface any prior decisions, constraints, or context that the receiving agent will need.
+
+3. Build the **handoff packet** — record it with `ck_memory_record` (type: `decision`, scope: `session`) containing:
+   - **What was accomplished** this session (bullet list of completed work with file paths)
+   - **What remains** (ordered list of next steps, from most to least critical)
+   - **Open findings** — any blocked or warning-level issues the receiving agent must address first
+   - **Constraints** — must-not-change areas, budget limits, compliance requirements discovered this session
+   - **Assumptions** — decisions made without explicit human confirmation that the receiving agent should be aware of
+   - **Resume hint** — the single most important thing the next agent should do first
+
+4. Call `ck_goal` (mode: `read`) to confirm the goal record is current. If it has drifted from what was actually worked on, update it with `ck_goal` (mode: `record`) before handing off.
+
+5. Call `ck_route` to determine the best agent or execution mode for the remaining work. Provide the remaining task list and any constraints.
+
+6. Call `ck_delegate` with the handoff packet as context and the routing recommendation from step 5. Use mode `handoff` for human-mediated transfer or mode `runtime` for automated background execution.
+
+7. Confirm to the user:
+   - What was preserved (memory record ID)
+   - Where the work is going (agent / mode)
+   - The single next action for the receiving agent
+   - How to resume: what to tell the next agent to pick up seamlessly
+
+## Non-negotiable rules
+
+- Never hand off with open **blocked** findings. Resolve or escalate them first — a blocked finding handed off unresolved will stall the receiving agent immediately.
+- The handoff packet must be complete enough that the receiving agent can continue **without** reading this session's conversation history.
+- If `ck_route` returns no suitable agent, tell the user explicitly rather than handing off to a mismatched executor.
+
+## What you produce
+
+At the end of this skill:
+- A `ck_memory_record` entry (type: `decision`) containing the full handoff packet
+- A `ck_delegate` call that initiates the transfer
+- A clear user-facing summary: what was saved, where work is going, and what the next agent will do first
+
+## Additional resources
+
+- For proof preservation before handoff, run the `proof-memory` skill first
+- For routing decisions, see `ck_route` tool documentation

package/.opencode/skills/plan-slice/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: plan-slice
+description: "Decompose an aligned goal into independently executable vertical slices with explicit blocking relationships. Each slice must cross all touched system layers — not a single layer. Submit for human approval before any implementation begins."
+when_to_use: "Activate after the align skill has produced a recorded goal, and before any code or delegation begins. Also activate when a goal has more than one system layer or more than two sequential tasks."
+argument-hint: "[aligned goal or ck_goal record ID]"
+license: Apache-2.0
+compatibility:
+  - codex
+  - claude-standalone
+  - claude-plugin
+  - copilot-plugin
+  - github-repo
+  - open-standard
+metadata:
+  author: controlkeel
+  version: "1.0"
+  category: planning
+  ck_mcp_tools:
+    - ck_context
+    - ck_goal
+    - ck_memory_record
+    - ck_memory_search
+    - ck_review_submit
+    - ck_review_status
+    - ck_route
+---
+
+# Plan Slice Skill
+
+Turn an aligned goal into a **directed acyclic graph of vertical slices** that agents can execute independently. Vertical slices give you working software at the end of each slice and feedback across all layers immediately — not at the end of phase 3 when three layers have already diverged.
+
+## Why vertical slices matter
+
+Agents default to horizontal work: all schema changes in phase 1, all API changes in phase 2, all UI in phase 3. This delays feedback on whether layers actually fit together until late in the work. A vertical slice crosses schema + service + UI (or whichever layers are touched) in one shot, so each slice is demonstrably working software — not a half-built layer.
+
+## Protocol
+
+### 1. Load context
+Call `ck_context` and `ck_memory_search` to retrieve the aligned goal, recorded decisions, and touched layers from the `align` step.
+
+### 2. Map system layers
+List every layer the goal touches. Common layers in order (innermost first):
+- **schema** — database tables, migrations, indexes
+- **service** — business logic, background jobs, domain rules
+- **api** — HTTP handlers, resolvers, RPC endpoints
+- **ui** — components, pages, forms, interactions
+- **infra** — CI/CD, environment config, feature flags, third-party credentials
+
+Not every goal touches all layers. Record which ones are in scope.
+
+### 3. Draft vertical slices
+
+Each slice must:
+- Touch **at least two adjacent layers** from the list above (one-layer slices are horizontal — flag them and expand or merge).
+- Deliver something observable or testable at its boundary (a working endpoint, a rendered component, a passing integration test).
+- Be **independently grabbable**: another agent or developer can pick it up given only the slice description and the outputs of its blocking slices.
+
+Start with the **thinnest possible vertical slice first** — often called the tracer bullet. This is the minimal path through all touched layers: one user story, one schema column, one endpoint, one UI element. It proves the layers fit together before you build breadth.
+
+Structure:
+```
+Slice 1 (tracer): <minimal cross-layer path> — AFK
+Slice 2: <next user story, depends on slice 1> — AFK
+Slice 3: <requires a design decision> — HiTL
+Slice 4: <final integration / edge cases, depends on 2 and 3> — AFK
+```
+
+### 4. Validate each slice
+
+For every proposed slice, check:
+- Does it touch only one layer? → **Horizontal slice — expand or merge.**
+- Does it produce something testable by the end? → If not, split differently.
+- Could another agent start it in isolation given its inputs? → If not, clarify the interface contract.
+- Does it contain unresolved design decisions? → Label it **HiTL** (supervised_execute or human_gate); clear decisions → label **AFK** (guarded_autonomy).
+
+### 5. Define blocking relationships
+
+Produce an explicit dependency list:
+```
+Slice 2 blocked by: Slice 1
+Slice 3 blocked by: Slice 1
+Slice 4 blocked by: Slice 2, Slice 3
+```
+
+Slices with no dependencies can run in parallel via `ck_route` + `ck_delegate`. Document which slices are parallelizable.
+
+### 6. Label autonomy mode per slice
+
+Map each slice to a CK autonomy profile:
+- **AFK** → `guarded_autonomy`: well-defined inputs/outputs, no open design questions, validation loop is deterministic.
+- **HiTL** → `supervised_execute`: contains a design decision, requires human judgment, or touches a critical path (auth, payments, schema migration, compliance-sensitive data).
+
+Never label a slice AFK if it contains an unresolved unknown from the `align` step.
+
+### 7. Record the plan
+Call `ck_memory_record` (type: `decision`) with the full slice plan: slice titles, layer coverage, blocking relationships, and autonomy labels.
+
+Update the `ck_goal` record (mode: `update_status`) with `active` and a progress note pointing to the slice plan.
+
+### 8. Submit for human approval
+
+Call `ck_review_submit` with:
+- `review_type`: `plan`
+- `plan_phase`: `implementation_plan`
+- `implementation_steps`: the slice list with blocking relationships and autonomy labels
+- `validation_plan`: which tests or observables prove each slice is done
+- `alignment_context`: the accepted goal from the `align` step
+- `scope_estimate`: number of slices, estimated touch points per layer
+
+Then call `ck_review_status` to check for `grill_questions`. Surface every grill question back to the user and resolve them before implementation begins. This is still human-in-the-loop — do not start coding until the review is approved.
+
+## Non-negotiable rules
+
+- Never begin implementation before the review is approved.
+- A slice that touches only one layer is not a vertical slice — it is a horizontal slice. Reject it.
+- AFK slices must have zero open design questions. If you find one, promote the slice to HiTL.
+- Parallelism is only valid between slices with no blocking relationship. Never run blocking slices in parallel.
+- The first slice must always be the thinnest viable cross-layer path. Do not start with setup or scaffolding that produces no observable output.
+
+## What you produce
+
+At the end of this skill:
+- A reviewed and approved slice plan (via `ck_review_submit`).
+- A `ck_memory_record` containing the DAG: slice titles, layers, dependencies, autonomy labels.
+- A `ck_goal` update marking the plan as active.
+- A clear first slice ready for handoff to implementation (via `ck_delegate` or direct agent work under the governance skill).
+
+## Additional resources
+
+- For the full governed workflow, see [references/workflow.md](references/workflow.md)

package/package.json

@@ -35,5 +35,5 @@
     "url": "git+https://github.com/aryaminus/controlkeel.git"
   },
   "type": "module",
-  "version": "0.3.1"
+  "version": "0.3.2"
 }