feat(cstack): add planning-mode

skills/planning-mode/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: planning-mode
+description: Plan new work and resume planning from natural-language or voice requests. Default to planning when intent is uncertain, produce a reviewed Ready handoff, and stop before execution.
+---
+
+# Planning mode
+
+Planning Mode turns an uncertain request into an exact, independently reviewed Ready handoff. It keeps the tracker canonical, carries settled decisions forward, and stops before execution.
+
+## Authority
+
+Planning Mode never creates, reuses, updates, or completes a native goal. It does not create an automation, heartbeat, persistent agent thread, or execution task. It may inspect evidence, use read-only helpers, update planning records within existing write authority, and run an explicitly authorized disposable prototype.
+
+Planning Mode does not install or configure products, edit product code or assets, reorganize operational chats, or dispatch implementation. Planning assent such as `yes`, `agreed`, `let's do it`, or `continue` settles a planning choice only. Execution requires a later user message that names the exact Ready revision and endpoint.
+
+Every future implementation handoff targets a different user-visible task. Prefer an existing dedicated Builder task. If none exists, prepare `new-task` as the destination and record that its creation awaits later explicit execution authorization. A subagent inside the planning task does not satisfy this separation.
+
+Current user decisions outrank historical notes. Tracker records outrank chat reconstruction. Missing evidence blocks only the decisions that depend on it. Continue independent planning branches while another branch waits.
+
+Before any final response, reconcile every included branch and take the next permitted planning step whenever one remains. A saved answer, checkpoint, research result, or Ready slice does not end larger included scope. Keep commentary updates going while work continues. Yield only for the sole remaining material user question, a real access, tool, or runtime limit, explicit pause or cancellation, or independently reviewed Ready coverage for the requested included scope. At a non-completion yield, state the exact question or blocker and the retained next action.
+
+Answer simple questions and small non-implementation requests directly. Use this workflow for material work. If the requested included scope already has independently reviewed Ready coverage, verify its exact receipts, present the handoff, and stop.
+
+## Required references
+
+Read a reference before its named operation. Resolve each path relative to this file.
+
+- Before recovering state, changing state, resuming work, or auditing map completion, read [references/lifecycle.md](references/lifecycle.md).
+- Before creating or changing a tracker record, snapshot, manifest, or receipt, read [references/records.md](references/records.md).
+- Before research, grilling, prototyping, visual work, or artifact handling, read [references/evidence.md](references/evidence.md).
+- Before readiness review, executor qualification, or presenting a handoff, read [references/handoff.md](references/handoff.md).
+- Before defining, running, or evaluating proof, read [references/verification.md](references/verification.md).
+
+Each reference is mandatory for its operation. If a required file is missing or unreadable, stop that operation before producing its output or mutation. Report the exact path, what could not proceed, and the action needed to restore the file. Continue unrelated work when its own inputs remain valid.
+
+## Planning sequence
+
+1. **Recover the tracker.** Read live tracker membership, relationships, bodies, relevant comments, revisions, checkpoints, and open review findings. Resume at the earliest unmet guard. Verify the planning destination, access, visibility, and existing write authority before a write.
+2. **Inspect evidence and standards.** Read applicable global and repository instructions, primary evidence, affected files, and current model policy before selecting any worker or reviewer. Record facts, user decisions, proposals, assumptions, conflicts, and missing evidence separately.
+3. **Map and grill.** Preserve a small decision tree in the current record. Promote that same map when independent branches, independent Ready slices, or partial invalidation appear. Ask the full currently answerable decision frontier with evidence, viable choices, tradeoffs, and a recommendation. Wait for the human on material choices. Recompute the frontier after each answer.
+4. **Synthesize records.** Create grouped decision records when questions become specifiable and implementation records when coherent scope exists. Keep one owner for each fact. Record complete conditional design, exclusions, dependencies, impact links, artifacts, authority, failure and recovery, and acceptance-to-proof mappings.
+5. **Review the exact revision.** Obtain the required independent readiness review against the original request, current decisions, primary evidence, scope, access, ownership, dependencies, recovery, and proof. Resolve routine findings within scope. Return material choices to the user. Recheck changed material.
+6. **Present Ready accurately.** Mark only an exact independently passed revision Ready. Present its ticket, revision, snapshot and manifest hashes, review receipt, proof recipe, endpoint, and unresolved excluded work. A Ready slice may be prepared for later authorized execution while other included branches continue. Claim the full map Ready and stop only when every included branch passes the completion audit.
+
+Planning records may describe a later execution receipt. They never constitute dispatch. A Ready label never grants execution, merge, deployment, publication, paid generation, or another external effect.
+
+## Composition
+
+Use installed methods as bounded methods under the current request and tracker decisions. Read each method when its trigger in [references/evidence.md](references/evidence.md) or [references/handoff.md](references/handoff.md) fires. Preserve vendor files and invocation metadata. If automatic invocation is unavailable, apply the method through its supported instructions without claiming hook or skill activation.
+
+This package defines guidance and records. It adds no hook, permission layer, model registry, tracker service, or runtime lock.

skills/planning-mode/references/evidence.md

@@ -0,0 +1,61 @@
+# Decisions, evidence, and artifacts
+
+Read this file before research, grilling, prototypes, visuals, or artifact work.
+
+## Materiality and intake
+
+A question is material when different answers change the product outcome, public or domain language, architecture, stored data, permissions, privacy, cost, rights, delivery authority, dependencies, acceptance, or proof. Record the question and its affected branches.
+
+Start with the user's requested outcome. Use problem-first intake when the problem, user, current behavior, or success condition is unclear. Do not force a full interview when those facts are already settled.
+
+Classify evidence as `VERIFIED`, `PROVISIONAL`, `CONFLICTING`, `MISSING`, or `UNAVAILABLE`. State what each item proves and its limits. Prefer the cheapest observation that can decide the question. Stop gathering evidence when another source cannot change a current material decision, acceptance criterion, or risk disposition. This is the Q39 stop rule.
+
+Missing or conflicting evidence blocks only dependent decisions. Continue independent branches.
+
+## Installed methods and read triggers
+
+Use these resolved methods as bounded inputs. Read each file in full when its trigger fires. Current user decisions and tracker records govern scope and authority.
+
+- For a substantive product, architecture, process, or priority decision, read [Knowledge Librarian](/Users/cameron/.agents/skills/knowledge-librarian/SKILL.md) and retrieve a small current brief before advising.
+- For a bounded factual investigation that needs primary sources, read [Research](/Users/cameron/.agents/skills/research/SKILL.md).
+- For a planning question round, read [Grilling](/Users/cameron/.agents/skills/grilling/SKILL.md), [Domain Modeling](/Users/cameron/.agents/skills/domain-modeling/SKILL.md), and [Show Me](/Users/cameron/.agents/skills/show-me/SKILL.md). Use the smallest useful visual beside the questions.
+- For large uncertain work spanning sessions, read the pinned [Wayfinder method](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/wayfinder/SKILL.md) and current tracker operations.
+- Before turning settled decisions into a specification or implementation records, read [To Spec](/Users/cameron/.agents/skills/to-spec/SKILL.md) and [To Tickets](/Users/cameron/.agents/skills/to-tickets/SKILL.md).
+
+If a method is absent, unreadable, explicit-only, or unsupported in the active runtime, record that fact and use only an approved bounded fallback. Do not claim automatic activation, another host's Skill API, or inherited authority. Keep vendor packages unchanged.
+
+## Decision rounds
+
+For every currently answerable material question:
+
+1. State the recommendation first and cite the evidence that supports it.
+2. Include only materially distinct viable alternatives. State the tradeoff and when each wins.
+3. Show the smallest useful Mermaid diagram, literal tree, comparison, or concrete example when it clarifies the choice.
+4. Ask the full answerable frontier for that round. Wait for the user's decisions.
+5. Record each answer, source, reason, affected records, and reopening observation. Recompute the frontier.
+
+The user decides preferences, product tradeoffs, authority, and other material choices. The lead retrieves facts and settles routine technical details inside approved scope.
+
+## Prototypes
+
+A prototype has one status: `Proposed`, `Isolated`, `Evidence captured`, `Disposed`, or `Promoted by implementation contract`.
+
+Use a disposable prototype only when observation can settle a material question. Name the question, allowed files and runtime, cost, expected observation, disposal owner, and stop condition first. Free isolated work may proceed within existing authority. Paid generation needs exact bounded approval.
+
+Retain the prompt, inputs, settings, requested and observed model or tool route when available, outputs for the approved batch or fallback, reasons, hashes, and intended downstream use. A prototype becomes production work only through an approved implementation contract. Dispose of run-owned resources or record the exact promotion.
+
+## Visual and creative evidence
+
+Use Mermaid for flows. Use fenced monospace trees for literal hierarchy. Use Visualize only when explicitly invoked. Use Canvas or Sites only when their actual deliverable is in scope.
+
+Identify each reference image and creative sample by source, rights status, hash or stable revision, approved traits, rejected traits, and allowed downstream use. Approval of a style reference does not grant permission to copy protected content or ship a prototype.
+
+For a decision-bearing visual, inspect the rendered result. Syntax success alone is not visual proof. For a required original, retrieve it through a supported path, compare its SHA-256 with the recorded bytes, and open it in the intended consumer before Ready. An invalid link, inaccessible original, altered hash, or failed rendering blocks the dependent Ready claim.
+
+## Artifact ownership
+
+Attach or link artifacts from their owning ticket. Preserve current private access. Use an existing large-file convention when one applies. Treat unavailable storage as a dependency. Do not install storage, LFS, hosting, publication, or migration during planning.
+
+After every artifact or tracker write, read back saved content and rendered structure. Keep raw content and hashes. Keep screenshots when visual meaning matters.
+
+Use LikeC4 only when settled architecture meaning needs a durable versioned view of systems, components, trust, deployment, data, or interactions. Its first use needs a separately authorized repository-local pinned pilot. That later contract must cover formatting, validation, a self-contained `index.html`, no remote assets, disconnected opening, visual inspection, traceability, editability, and reconciliation with implementation. Planning Mode does not install or host LikeC4.

skills/planning-mode/references/handoff.md

@@ -0,0 +1,59 @@
+# Readiness review and handoff
+
+Read this file before readiness review, executor qualification, or presenting Ready.
+
+## Review input
+
+Give the reviewer the exact original request, current approved decisions, primary evidence, ticket body snapshot, source manifest, applicable standards, artifacts, acceptance-to-proof map, and delivery authority. The reviewer inspects these before implementer conclusions.
+
+Keep two review roles distinct:
+
+- Routine per-ticket review checks the implementation contract through the alternate-family or other route required by current policy.
+- The final phase-one readiness audit checks the complete map through the current global readiness route.
+
+Resolve both roles from the current `/Users/cameron/.codex/pstack-models.md`. Do not hardcode model names in this package. Record requested and observed role, model, effort, provider, and failover when the runtime exposes them. Unknown fields stay unknown. A configured route does not prove an observed route or family diversity.
+
+## Verdict
+
+The independent reviewer returns one result for the exact revision:
+
+- `READY` means the reviewer found no unresolved material gap in behavior, scope, access, ownership, dependencies, failure and recovery, or proof.
+- `FINDINGS` lists severity, primary evidence, why autonomy is blocked when applicable, and the smallest correction.
+
+The lead resolves routine technical findings inside the approved scope. Return product, design, authority, access, or acceptance choices to the user. Obtain a focused recheck for changed material. Missing access, route, runtime, or proof remains a failed gate. A new successful run does not erase an earlier failure.
+
+## Executor qualification
+
+Select a different user-visible task for every future implementation handoff. Prefer an existing dedicated Builder task. If none exists, prepare a `new-task` destination whose creation waits for later explicit execution authorization. A subagent inside the planning task does not satisfy this separation. Destination identity is opaque and does not depend on a memory product.
+
+Before reuse or later creation, inspect the destination task, its recovered checkpoint, acknowledgement, and prior dispatch evidence. Record the destination mode, identity when present, recovered checkpoint, creation-authority state, selected executor playbook, and duplicate-dispatch check. Keep the planning-readiness owner separate from the destination task's fresh independent implementation-review owner. The destination task owns implementation, verification, progress, implementation review, and completion evidence.
+
+For Poteto execution, read these current installed files before Ready:
+
+- [Poteto entrypoint](/Users/cameron/.codex/plugins/cache/pstack-for-codex-local/pstack-for-codex/0.1.0/skills/poteto-mode/SKILL.md)
+- [Poteto runtime contract](/Users/cameron/.codex/plugins/cache/pstack-for-codex-local/pstack-for-codex/0.1.0/skills/poteto-mode/references/codex-agent-runtime.md)
+- [Authoring a skill playbook](/Users/cameron/.codex/plugins/cache/pstack-for-codex-local/pstack-for-codex/0.1.0/skills/poteto-mode/playbooks/authoring-a-skill.md) when the work creates or edits a skill
+- [Portable Poteto persona](/Users/cameron/.codex/plugins/cache/pstack-for-codex-local/pstack-for-codex/0.1.0/skills/poteto-mode/references/poteto-agent-prompt.md) when the custom profile is unavailable
+
+Read any method reached by that playbook, including current skill authoring and agent-writing guidance. Record each mandatory step with its evidence or explicit approved disposition. Current user authority overrides upstream PR or activation defaults. An unresolved conflict keeps the route unqualified.
+
+## Runtime ownership and recovery
+
+The handoff names owned checkout and files plus every relevant port, process, service, container, database, browser profile, editor or engine session, and user-data directory. Use existing supported reservation and cooperative checkpoint mechanisms. Serialize shared mutable resources. Do not add an ownership service.
+
+The executor owns only named resources. Cleanup removes only run-owned resources. After interruption, inspect actual files, processes, external effects, and checkpoints before one bounded retry. A missing acknowledgement does not prove that no work occurred.
+
+## Ready handoff
+
+Before preparing or presenting a Ready slice, verify:
+
+- The ticket and manifest hashes match the current reviewed payload and artifacts.
+- The independent receipt covers the slice's exact current revision.
+- The destination mode, identity when present, recovered checkpoint, creation-authority state, selected executor playbook, and duplicate-dispatch check are explicit.
+- The planning-readiness owner and the implementation-review owner are separate and explicit.
+- The executor, files, runtime, dependencies, endpoint, forbidden effects, proof, and recovery are explicit.
+- Historical failures and excluded work remain visible with their true status.
+
+Present the exact Ready ticket and revision, evidence, review receipt, proof recipe, authorized endpoint, and unresolved excluded work. A Ready slice may be prepared for later authorized execution while other included branches continue. Reconcile the map and take the next permitted planning step after presenting that slice. Claim the full map Ready and stop only when every included branch passes the completion audit.
+
+For a Ready slice, the later execution action is a distinct user message that names the exact revision and endpoint. Planning Mode does not create a goal, schedule work, create an operational task, dispatch an executor, mutate the target, apply files, merge, deploy, publish, or pay for a service.