sdcorejs-plan

name	sdcorejs-plan
description	Plan authoring and approval gate. Use after approved spec, or when the user asks to write/review/approve/change an implementation plan. Produces numbered file/task plan, self-reviews, waits for explicit approval, then persists approved snapshot under .sdcorejs/plans/<track>/ before execute-plan. Applies across tracks. Runtime-localized.

Codex path resolution: Resolve ../_refs/... relative to this SKILL.md. Resolve another SDCoreJS skill by opening the sibling folder ../<skill-name>/SKILL.md.

03 - Plan

Shared Protocols

Before executing this skill:

1. Read and apply ../_refs/shared/tasklist.md for non-trivial execution tasks.
2. Read and apply ../_refs/shared/persona.md if a project persona exists.
3. Read and apply ../_refs/shared/project-context.md for project memory, resume checkpoints, summaries, specs/plans, tasks, and relevant memories.
4. Current user request, current files, diffs, logs, failing tests, and command output override stored context.
5. Before presenting user-facing choices, approval gates, yes/no questions, or mode selections, read and apply ../_refs/shared/user-choice-prompt.md so options are presented as sequential numbered choices.

Purpose

Translate an approved spec into an executable contract, hold the user approval gate, and persist the approved plan corpus inside the same skill.

The plan is the exact contract that sdcorejs-execute-plan runs.

Preconditions

• A spec has explicit user approval.
• sdcorejs-spec has written the approved spec snapshot.
• The plan must consume spec_context, reference the approved spec path, and include the approved spec hash.

If the spec is missing or unapproved, route to sdcorejs-spec.

Before drafting, apply ../_refs/shared/project-context.md with:

caller_context: sdcorejs-plan
context_mode: summary-read
side_effects_allowed: true

Plan writes are limited to the draft and approved plan artifacts owned by this skill. Missing or stale summary is not permission to refresh context. Preserve contract_id, requirement_id, target_root, target_root_kind, track, stack_profile, approved_spec_path, and approved_spec_hash from spec_context.

Process

1. Load inputs

Read:

• Approved spec.
• spec_context, including approved_spec_path, approved_spec_hash, target_root_kind, stack_profile, assumptions, risks, non-goals, and approval metadata.
• Relevant ../_refs/sdlc/<track>.md for angular / nestjs / nextjs.
• ../_refs/shared/testing-philosophy.md and target stack test ref for test-track plans.
• Existing .sdcorejs/docs/product/ ledgers for product-track plans.
• Latest 1-3 approved plans under .sdcorejs/plans/<track>/ to mirror the user's preferred granularity.
• package.json, packageManager, lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lockb/bun.lock), workspace config, and package.json scripts. Record package manager/script evidence instead of guessing commands.

2. Check paths

Before drafting:

• Confirm every CREATE path does not already exist.
• Confirm every EDIT path does exist.
• Surface conflicts instead of silently overwriting.
• For generic harness plans, mark unknown paths as VERIFY THEN EDIT instead of pretending they are known.
• Define allowed_paths, prohibited_paths, generated_artifacts, and docs_artifacts. If a path is unknown, say "discover target path during execution" and give the path-selection rule instead of inventing a path.
• Mark shared files such as package.json, lockfiles, routing modules, app-level providers, generated mirrors, global configs, env files, public API files, and frozen contracts as coordination-risk paths.
• Record dependency, env, and migration boundaries. Dependency, env, package manifest, lockfile, or migration writes require explicit plan approval.

2.1 Working-tree and write-scope preflight plan

The plan must tell sdcorejs-execute-plan to run this preflight before edits:

• git status --short
• staged diffstat
• unstaged diffstat
• untracked files
• current branch
• current HEAD
• allowed_paths and prohibited_paths from plan_context
• unrelated dirty files
• target_root_kind authoring-repo guard

If unrelated dirty files exist, execution asks:

1. Continue but restrict edits to approved plan-scoped files
2. Continue and allow touching selected dirty files
3. Stop so the user can clean or stash changes first

Do not plan edits to prohibited paths, env values, secrets, generated/vendor/ build output, lockfiles, or package manifests unless the approved plan allows them.

3. Draft the plan

Use numbered steps grouped by phase:

## Scope
<2-4 lines from the approved spec>

## Execution context
- Track: <angular|nestjs|nextjs|test|product|generic>
- Target root kind: <target_root_kind>
- Stack profile: <stack_profile>
- Coverage approach: <post-hoc|TDD>
- Parallel candidates: <yes/no + why>

```yaml
plan_context:
  source: sdcorejs-plan
  contract_id: <contract id>
  requirement_id: <requirement id>
  approved_spec_path: <path>
  approved_spec_hash: <hash>
  approved_plan_path: <empty until approved>
  approved_plan_hash: <empty until approved>
  supersedes: <prior approved plan path or null>
  target_root: <target root>
  target_root_kind: target-project | sdcorejs-agent-authoring-repo | skill-pack-authoring-repo | unknown
  track: <track>
  stack_profile: <stack profile>
  task_count: <N>
  phase_count: <M>
  allowed_paths:
    - <path or glob>
  prohibited_paths:
    - <path or glob>
  generated_artifacts:
    - <path or glob>
  docs_artifacts:
    - <path or glob>
  dependency_changes:
    required: true | false
    packages:
      - <name or empty>
    approval_required: true | false
  env_changes:
    required: true | false
    files:
      - <path or empty>
    approval_required: true | false
  migration_changes:
    required: true | false
    description: <text or null>
    approval_required: true | false
  verification_strategy:
    package_manager: <npm|pnpm|yarn|bun|unknown>
    scripts_detected:
      - name: <script name>
    commands_planned:
      - command_or_script: <detected command or script>
        reason: <why this proves the change>
    commands_skipped:
      - command_or_probe: <candidate skipped>
        reason: <why skipped>
    focused_checks:
      - <check>
    broad_checks:
      - <check>
  parallel_candidates:
    allowed: true | false
    frozen_contract:
      path: <path or embedded>
      hash: <hash>
      revision: <integer>
      derived_from_approved_plan_hash: <hash after approval>
      supersedes: <prior contract id or null>
    units:
      - id: <stable id>
        title: <title>
        role: <plan-derived role or null>
        depends_on:
          - <unit id or empty>
        produces:
          - <artifact or empty>
        consumes:
          - <artifact or empty>
        allowed_paths:
          - <path or glob>
        prohibited_paths:
          - <path or glob>
        exclusive_resources:
          - <resource or empty>
        shared_readonly_resources:
          - <resource or empty>
        result_type: commit | patch | working-tree-diff | report
        verification_command: <detected command or manual check>
    shared_files:
      - path: <path>
        owner: <unit-id> | integration-unit | parent-contract-only
        coordination_strategy: <sequential | wave-gated | do-not-touch>
    conflict_risks:
      - <risk>
  finish_tail:
    docs_before_final_branch_ready: true
    verify_before_done: true
    branch_ready_final_gate: true
    no_writes_after_branch_ready: true
  approval:
    approved: false
    approved_at: null
  change_control:
    revision: <integer>
    supersedes: <prior approved plan path or null>
    change_reason: <reason or null>
```

## Tasks

### Phase 1 - <phase name>
1. CREATE <path> - <intent>
2. EDIT <path> - <intent>

### Phase 2 - Tests / verification
3. CREATE <path> - <intent>

## Acceptance mapping
- AC1 -> tasks 1, 3
- AC2 -> tasks 2, 3

## Verification
- `<detected package-manager command or existing script>`
- Manual: <smoke check>

For test-track plans, steps can be test cases, fixtures, page objects, harness scripts, and runner commands. For product-track plans, steps can be ledger creation, story/AC refinement, implementation map update, test map update, UAT checklist, and traceability audit. For generic harness plans, every task must name the tool/action and verification evidence.

4. Self-review before showing the user

Fix the plan before presenting if any checklist item fails:

• No placeholders.
• Every task has a number, action marker, target path or command, and one-line intent.
• Acceptance criteria map to at least one task.
• Verification section has commands discovered from package manager/script evidence or explicit manual checks. If no script exists, record commands_skipped with the reason instead of inventing one.
• Path conflicts are surfaced.
• Test coverage matches the spec's coverage approach.
• Parallel candidates are identified, but not executed.
• The plan does not hardcode npm, npx, tsc, Playwright, browser installs, or any package manager as universal defaults. Do not hardcode npm/npx as universal commands, and do not use npx --yes or downloading probes without explicit approval.
• The plan does not mix package managers.
• Dependency/env/migration/package manifest/lockfile writes are explicitly approved or marked out of scope.
• No write-producing step occurs after final branch-ready.

5. Present the approval gate

Show a concise summary:

Plan ready: <N> tasks across <M> phases.

Phases:
- Phase 1: tasks 1-K
- Phase 2: tasks K+1...

Verification:
- <command>
- Manual: <check>

Do you approve this plan?

Options:
1. Approve - snapshot the plan and move to execute-plan.
2. Change - name the step or phase to update, then I will revise it.
3. Cancel - stop here.

Reply with `1`, `2`, or `3`. If you choose `2`, describe the change.

Translate at runtime.

6. Handle user response

Approve:

1. Write an immutable approved-plan snapshot under:

<target-project>/.sdcorejs/plans/<track>/<YYYY-MM-DD-HH-mm>-<kebab-topic>.md

Compute approved_plan_hash over the canonical approved plan body, excluding frontmatter and the approved_plan_hash field, so the hash is not self-referential.

2. Include frontmatter:

---
name: <kebab-topic>
description: <one-line future-loading hook>
approvedAt: <ISO-8601 timestamp with timezone>
approvedBy: <git user.email or session user when known>
track: <angular|nestjs|nextjs|test|product|generic>
sourceSpecPath: .sdcorejs/specs/<track>/<timestamp>-<topic>.md
taskCount: <N>
phaseCount: <M>
target_root_kind: target-project | sdcorejs-agent-authoring-repo | skill-pack-authoring-repo | unknown
stack_profile: <stack profile>
approved_spec_hash: <sha256 from spec_context>
allowed_paths:
  - <path or glob>
prohibited_paths:
  - <path or glob>
dependency_changes:
  required: true | false
  approval_required: true | false
env_changes:
  required: true | false
  approval_required: true | false
migration_changes:
  required: true | false
  approval_required: true | false
approved_plan_hash: <sha256 of approved plan body excluding frontmatter and this hash field>
supersedes: <prior approved plan path or null>
change_control:
  revision: <integer>
  supersedes: <prior approved plan path or null>
  change_reason: <reason or null>
---

3. Body format:

# <Title> - Approved Plan

> Snapshot of what the user approved at the `sdcorejs-plan` gate. Do not edit by hand; re-author through `sdcorejs-plan` if the contract changes.

## Approved contract
<verbatim approved plan content>

## Decisions captured during review
- <what changed during review, or `(approved as drafted)`>

## Skill provenance
sdcorejs-plan (approved on attempt <N> / 3)

4. Emit final plan_context with approved_plan_path, approved_plan_hash, write scope, verification strategy, package-manager evidence, parallel candidates, dependency/env/migration boundaries, and change-control metadata.
5. Only after the approved snapshot succeeds, hand off to sdcorejs-execute-plan with the approved plan snapshot path and plan_context.

Change request:

1. Edit the plan.
2. Re-run self-review.
3. Re-present the summary.
4. Cap at 3 revision rounds, then suggest returning to sdcorejs-spec.

Abort:

1. Stop the workflow.
2. Do not write an approved snapshot.

Rules

Must do

• Keep code generation out of this skill.
• Wait for explicit plan approval.
• Snapshot the approved plan before execution.
• Create a new approved snapshot every time; snapshots are immutable history.
• Treat approved plans as immutable snapshots. If scope changes after approval, create a new plan revision with supersedes and change_reason.
• Preserve the latest approved plan that matches the current approved_spec_hash. If spec_context and plan_context hashes mismatch, stop and ask for plan regeneration.
• Record write scope, allowed paths, prohibited paths, generated artifact boundaries, docs artifacts, dependency changes, env changes, migration changes, verification strategy, package manager/script evidence, parallelization metadata, shared-file risks, and final tail ordering.
• Discover package manager from packageManager, lockfiles, and workspace config; read package.json scripts before planning commands.
• Record commands_planned, commands_skipped, focused checks, and broad checks with evidence.
• Capture review decisions honestly; never leave the section blank.
• Pass the approved plan as the exact execution contract to sdcorejs-execute-plan.
• Include verification commands.

Must not

• Dispatch a track orchestrator directly from this skill.
• Modify the plan after handing off without returning to the approval gate.
• Treat silence as approval.
• Hide a path conflict.
• Overwrite an old approved snapshot.
• Mutate an approved plan snapshot in place.
• Add dependencies, env files, migrations, package manifests, lockfiles, or generated/vendor/build output unless the approved plan explicitly allows it.
• Hardcode one package manager, mix package managers, invent missing scripts, or present npm/npx/tsc as universal defaults.
• Plan writes after final branch-ready.

Cross-references

• sdcorejs-spec - approved spec input
• sdcorejs-execute-plan - runs the approved plan