| name | sdcorejs-execute-plan |
| description | Execute an approved plan snapshot. Use after sdcorejs-plan approval or when asked to execute, run, generate from, or continue an approved plan for Angular, NestJS, Next.js, React, Node, fullstack, product, design, documentation, workflow, test, or generic/general work. Detects track/profile, preserves contract/write scope/package-manager evidence, asks sequential vs parallel, and invokes parallel-dispatch when approved. 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.
04 - Execute Plan
Shared Protocols
Before executing this skill:
- Read and apply
../_refs/shared/tasklist.md for non-trivial execution tasks.
- Read and apply
../_refs/shared/persona.md if a project persona exists.
- Read and apply
../_refs/shared/project-context.md for project memory, resume checkpoints, summaries, specs/plans, tasks, and relevant memories.
- Current user request, current files, diffs, logs, failing tests, and command output override stored context.
- 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
Run the approved plan as the execution contract. This skill is the handoff between planning and doing.
It owns four decisions:
- Which execution track should run.
- Whether the user wants sequential or parallel execution.
- Whether Angular work is Core UI portal work or plain Angular work.
- Whether NestJS, Next.js, React, Node/general, migration, product, design, or
test work needs a track executor or the generic harness fallback.
The generic harness is write-capable because it is the approved-plan fallback
executor for unsupported stacks and explicit CREATE/EDIT tasks. Write
permission is constrained by plan_context.allowed_paths,
plan_context.prohibited_paths, dependency/env/migration boundaries, and the
working-tree preflight below.
Preconditions
sdcorejs-plan has explicit user approval.sdcorejs-plan has written the approved plan snapshot.- The approved plan is available as a path or in context.
plan_context is present, including approved_spec_hash,
approved_plan_hash, target_root_kind, stack_profile, allowed_paths,
prohibited_paths, dependency/env/migration boundaries, verification
strategy, and parallel candidates.
If the plan is missing or unapproved, route back to sdcorejs-plan.
If the plan hash does not match the current approved spec hash, stop and ask for
sdcorejs-plan regeneration.
Step 0 - Context preflight
Before loading the plan or dispatching any executor, run sdcorejs-explore (summary-read) through ../_refs/shared/project-context.md.
- Use
summary-read by default. If the target root already exists and
<target>/.sdcorejs/summary.md is missing or stale, do not refresh
automatically. Run summary-refresh only when the approved plan explicitly
allows a context write or the user approves the refresh in this execution
session; record the write in explore_context.
- If the summary exists and is fresh enough, read it before choosing the
executor.
- If the approved plan creates a brand-new target root that does not exist yet,
record this exception and require the owning executor to run
sdcorejs-explore (summary-refresh) immediately after the first scaffold lands.
- Treat the approved plan and current evidence as stronger than stored context
when they conflict.
Step 0.5 - Working-tree preflight
Before any edit or subagent dispatch, inspect the current working tree and
compare it to plan_context:
git status --short- staged diffstat
- unstaged diffstat
- untracked files
- current branch
- current_HEAD
- target_root_kind
- allowed_paths
- prohibited_paths
- unrelated dirty files
- status snapshot hash and dirty diff hash
- intended output paths that already exist or overlap dirty paths
If unrelated dirty files exist, ask one numbered decision before editing:
Working tree has changes outside this approved plan.
Options:
1. Continue but restrict edits to approved plan-scoped files
2. Continue and allow touching selected dirty files
3. Stop so you can clean or stash changes first
Reply with `1`, `2`, or `3`.
Do not edit prohibited paths without explicit approval and plan revision. Do not
edit env files, secret files, generated/vendor/build output, lockfiles, package
manifests, or migrations unless plan_context explicitly allows it. If
target_root_kind is sdcorejs-agent-authoring-repo or
skill-pack-authoring-repo, confirm that the authoring repo itself is the
intended target before writing.
For direct sdcorejs-parallel-dispatch entry, pass this same preflight as the
protocol-v2 working_tree block. Direct dispatch is not permission to bypass
branch/HEAD, dirty-state, untracked-file, or intended-output checks.
Process
1. Load the approved plan
Read the plan from .sdcorejs/plans/<track>/ or the plan path supplied by sdcorejs-plan.
Extract:
plan_context.- Scope and acceptance criteria.
- Task list and phase order.
- File paths and commands.
- Coverage approach.
allowed_paths and prohibited_paths.- Dependency, env, and migration boundaries.
- Verification strategy,
commands_planned, and commands_skipped.
- Any declared parallel candidates.
- Solution-root layout when present (
product/, design/, backend/, frontend/, test/, .sdcorejs/).
2. Detect execution track
Prefer explicit track metadata in the plan. Otherwise infer from project signals and paths:
| Track | Signals | Executor |
|---|
| angular | core-ui-angular, legacy-core-ui-angular, approved migration-request, or new SDCoreJS portal creation | sdcorejs-angular |
| nestjs | sdcorejs-nestjs profile or approved SDCoreJS Nest migration | sdcorejs-nestjs |
| nextjs | nextjs-build-website profile or approved build-website/public-site migration | sdcorejs-nextjs |
| react | react-vite, react-cra, or generic React component/app work | generic harness fallback |
| node | node-general, scripts/config/library work | generic harness fallback |
| product | product docs, PO docs, user stories, acceptance criteria, UAT, traceability matrix, requirement/implementation/test gap review | sdcorejs-product |
| design | design docs, wireframes, mockups, UI/UX, screen flow, PNG previews, FE handoff, story-to-screen mapping | sdcorejs-design |
| test | test-only plan, *.spec.*, e2e, Playwright/Cypress/Robot/Jest, inspector export | sdcorejs-test |
| generic | unsupported stack, docs/scripts/config changes, mixed non-track work | generic harness fallback |
Angular project classification preflight
Before dispatching any Angular executor, classify the target project. Use the
approved plan, package manifests, lockfiles, existing imports, and current user
request. Record the classification in the execution summary.
| Classification | Evidence | Executor/fallback |
|---|
core-ui-angular | Existing Angular app depends on or imports @sdcorejs/angular | sdcorejs-angular; generate imports with @sdcorejs/angular |
legacy-core-ui-angular | Existing Angular app depends on or imports @sd-angular/core | sdcorejs-angular; preserve @sd-angular/core imports |
plain-angular | Angular signals exist (angular.json, @angular/core, components, routes), but neither Core UI package is installed/imported | generic harness fallback; reuse local/shared/design-system components and installed UI libraries only |
migration-request | User or approved plan explicitly asks to install/adopt/migrate to SDCoreJS Core UI | return to sdcorejs-spec/sdcorejs-plan unless the dependency/migration scope is already explicitly approved |
non-angular | No Angular evidence | Continue non-Angular track detection |
Only dispatch sdcorejs-angular for core-ui-angular,
legacy-core-ui-angular, approved migration-request, or brand-new SDCoreJS
portal creation. Do not treat broad Angular signals alone (angular.json,
@angular/core, components, routes, or src/libs/**) as permission to run the
Core UI portal executor.
For plain-angular, run the generic harness. It must follow the real project
structure, never import @sdcorejs/angular or @sd-angular/core, never fetch
Core UI docs, never emit a Core UI usage summary, never force admin screens,
never assume src/libs/**/features/** when the project uses another structure,
and must ask for explicit approval before adding @sdcorejs/angular,
@sd-angular/core, or @angular/material.
Do not route plain Angular to sdcorejs-angular by default; plain-angular
uses the generic harness unless the approved plan is a migration request or
brand-new SDCoreJS portal creation.
NestJS project classification preflight
Use approved plan metadata, package manifests, imports, modules/controllers/
providers, and tests.
| Classification | Evidence | Executor/fallback |
|---|
sdcorejs-nestjs | NestJS app depends on/imports @sdcorejs/nestjs or strong SDCoreJS Nest conventions | sdcorejs-nestjs |
plain-nestjs | nest-cli.json, @nestjs/*, modules/controllers/providers, or Nest tests without SDCoreJS Nest evidence | generic harness fallback |
migration-request | Approved plan explicitly adopts SDCoreJS Nest conventions | sdcorejs-nestjs only when dependency/migration scope is approved |
Do not route plain NestJS to sdcorejs-nestjs by default. Do not assume
TypeORM, PostgreSQL, Zod, SdContext, @HasPermission, or @sdcorejs/nestjs
for plain-nestjs unless detected or approved.
Next.js and React classification preflight
Use approved plan metadata, next.config.*, React/Vite/CRA config, routes,
content/i18n structure, and tests.
| Classification | Evidence | Executor/fallback |
|---|
nextjs-build-website | Next.js plus public-site/build-website evidence such as [locale], typed i18n navigation, content/public-site structure, sitemap/OG plan, or prior build-website context | sdcorejs-nextjs |
plain-nextjs | Next.js app/router/page evidence without build-website profile | generic harness fallback |
react-next-generic | Next.js present but request is generic React app/dashboard behavior | generic harness fallback |
react-vite | Vite config plus React dependency | generic harness fallback |
react-cra | react-scripts | generic harness fallback |
node-general | Node package/scripts/config work without stronger framework | generic harness fallback |
general | unsupported or unknown stack | generic harness fallback |
Do not route plain Next.js to sdcorejs-nextjs by default. Do not assume
[locale], setRequestLocale, sitemap/public-site metadata, typed i18n
navigation, or content folders for plain-nextjs.
For mixed full-stack plans, classify as role-split and prepare to invoke sdcorejs-parallel-dispatch. If the plan came from sdcorejs-solution-builder, preserve the solution-root contract: product docs in product/, design handoff in design/, backend in backend/, frontend in frontend/, cross-stack tests in test/, and traceability/evidence in .sdcorejs/.
3. Always ask parallel vs sequential
Before any code/test generation, ask the user:
Execution mode?
Recommendation: <sequential|parallel> because <reason>.
Options:
1. Sequential - safer, easier to review, best for shared files or dependent steps. [Recommended when applicable]
2. Parallel - faster when tasks are independent; I will use the parallel-dispatch gate first. [Recommended when applicable]
Reply with `1` or `2`.
Translate at runtime. Do not execute until the user answers. If the user says "you decide", choose the recommendation and state it.
4. If parallel is chosen
Invoke sdcorejs-parallel-dispatch. It owns both the safety verdict and the safe parallel execution path.
- If verdict is
PARALLEL-CANDIDATE, it runs independent-unit fan-out.
- If verdict is
ROLE-SPLIT, it runs the product/design/backend/frontend/test-QC role-split loop.
- If verdict is
SEQUENTIAL, explain why parallel is unsafe and ask whether to
continue sequentially with 1. Continue sequentially (yes) /
2. Stop and revise plan (no).
5. If sequential is chosen
If the user requested isolation, or the plan is risky enough that isolation is
needed, invoke sdcorejs-git (workspace mode) before dispatching. That
mode reads ../_refs/orchestration/workspace-isolation.md and reports the baseline.
Dispatch by detected track:
- angular ->
sdcorejs-angular only when the Angular classification preflight allows it
- nestjs ->
sdcorejs-nestjs
- nextjs ->
sdcorejs-nextjs
- product ->
sdcorejs-product
- design ->
sdcorejs-design
- test ->
sdcorejs-test
- generic or
plain-angular -> run the harness fallback below
Pass the approved plan as the contract. The executor must not add scope without returning to sdcorejs-plan.
6. Generic harness fallback
Use the generic harness when no track-specific orchestrator matches.
- Create a progress checklist with one item per approved task plus finishing steps.
- Execute tasks in the approved order using the normal editing and shell tools,
including Write only for approved CREATE tasks.
- Keep edits inside
allowed_paths and outside prohibited_paths.
- Run every verification command from
plan_context.commands_planned; record
commands_run with exit codes and commands_skipped with reasons when a script,
tool, package manager, service, or environment is unavailable.
- If code changed, present the standard finish gate, run write-producing docs
or task artifacts before ship, then run
sdcorejs-ship (verify-before-done mode) and sdcorejs-ship (branch-ready mode) as the final read-only gate.
- If only docs/config changed, still run the planned verification and report
evidence.
The harness is intentionally conservative. If a task needs a domain-specific pattern not captured in the plan, stop and return to sdcorejs-plan.
7. Emit execution context
Before handing off, pausing, or reporting, produce execution_context:
execution_context:
source: sdcorejs-execute-plan
contract_id: <contract id>
requirement_id: <requirement id>
approved_spec_path: <path>
approved_spec_hash: <hash>
approved_plan_path: <path>
approved_plan_hash: <hash>
execution_mode: sequential | parallel | generic-harness | delegated-executor
target_root: <target root>
target_root_kind: target-project | sdcorejs-agent-authoring-repo | skill-pack-authoring-repo | unknown
track: <track>
stack_profile: <stack profile>
executor_selected: <skill or generic harness>
executor_reason: <short reason>
generic_harness_used: true | false
migration_request: true | false
working_tree_preflight:
current_HEAD: <sha>
dirty: true | false
staged: <summary>
unstaged: <summary>
untracked:
- <path>
unrelated_dirty_paths:
- <path>
tasks_completed:
- id: <task id>
summary: <summary>
files_changed:
- <path>
tasks_remaining:
- id: <task id>
reason: <reason>
files_changed:
- <path>
commands_run:
- command_or_script: <command>
exit_code: <code>
reason: <why run>
commands_skipped:
- command_or_probe: <command>
reason: <why skipped>
redaction_applied: true | false
ship_handoff:
required: true | false
verification_mode: feature-acceptance | bugfix-verification | docs-only-hygiene | specless-verification | dependency-regression | release-readiness
Rules
Must do
- Never execute without an approved plan snapshot.
- Consume
plan_context and preserve contract_id, approved_spec_hash,
approved_plan_hash, target_root_kind, track, stack_profile,
write-scope boundaries, package-manager evidence, and verification strategy.
- Always ask sequential vs parallel before execution.
- Use
sdcorejs-product as the executor for product-track ledgers and traceability audits.
- Use
sdcorejs-design as the executor for design-track FE handoff artifacts.
- Use
sdcorejs-test as the executor for test-track plans.
- Use the generic harness fallback when no track matches.
- Perform working-tree preflight before edits.
- Obey
allowed_paths and prohibited_paths.
- Use package-manager/script discovery from the plan. Do not mix package
managers, invent missing scripts, run unapproved installs, or use
npx --yes
without approval.
- Redact secrets and PII from execution summaries, task checkpoints, logs, and
handoffs.
- Verify success from real command output before claiming anything passed.
- Keep the user's language in status and summaries.
Must not
- Dispatch a track orchestrator before the parallel question is answered.
- Parallelize shared-file or dependent steps just because it looks faster.
- Let a subagent change the approved plan.
- Hide a
SEQUENTIAL verdict after the user asked for parallel.
- Skip finish-gate and mandatory tail steps after code generation.
- Edit outside approved scope.
- Mutate approved specs/plans instead of returning to the approval gate for a
revision.
- Route plain framework profiles to SDCoreJS-specific executors by default.
- Write after final branch-ready unless branch-ready is run again.
Cross-references
sdcorejs-plan - approved execution contractsdcorejs-parallel-dispatch - decides whether parallel is safe and executes safe fan-out or role-split worksdcorejs-git (workspace mode) - isolates work when requested or neededsdcorejs-angular, sdcorejs-nestjs, sdcorejs-nextjs, sdcorejs-product, sdcorejs-design, sdcorejs-test - track executorssdcorejs-ship (verify-before-done mode) - acceptance verification gate
