new-task

File Paths Reference

Skill Definition Files (read-only)

File	Path	Purpose
This file	templetes/new-task/SKILL.md	Skill definition and execution procedure
Input schema	templetes/new-task/references/input.template.yaml	Fields the agent reads from mission-spec.yaml
Output template	templetes/new-task/references/output.template.yaml	Structure of the generated task-spec
Rules	templetes/new-task/references/rules.md	ID conventions, contracts, execution plan rules, anti-patterns
Validator	templetes/new-task/scripts/validate.py	Pre-flight check of mission-spec.yaml

Runtime Files (created per task)

File	Path	Who creates it
Output	.ssdam/{id}/output/task-spec.TSK-NNN.yaml	This agent

{id} is the workspace ID from the mission (e.g., media-asset-platform-20260221). NNN is the 3-digit task number specified by the user (e.g., 001). The agent reads these files from the workspace:

• .ssdam/{id}/output/mission-spec.yaml ← required
• .ssdam/{id}/input/mission-input.yaml ← optional (for tech stack)

Skill Chain

[new-mission AgentSkill]
  ↓
[.ssdam/{id}/output/mission-spec.yaml]
  ↓
[User]: /new-task <path-to-mission-spec.yaml> <TSK-NNN>
        ↓
[new-task AgentSkill]  ← YOU ARE HERE
  PRE-EXECUTION: Validate mission-spec.yaml
  Phase 1–8: Load → Design → Plan → Validate → Write
        ↓
[.ssdam/{id}/output/task-spec.TSK-NNN.yaml]
        ↓
[Execution element chain]
  Execution → Artifact → Evaluation → Evidence → Checkpoint

---

Overview

Trigger	/new-task <path-to-mission-spec.yaml> <TSK-NNN>
Input	mission-spec.yaml (required) + mission-input.yaml (optional, same workspace)
Work	Validate → Load → Design contracts, criteria, execution plan (15 steps)
Output	.ssdam/{id}/output/task-spec.TSK-NNN.yaml
Previous skill	new-mission
Next element	Execution (the agent executes task-spec.TSK-NNN.yaml step by step)

The agent receives the path to mission-spec.yaml and the target task ID (TSK-NNN). It reads the mission spec, validates it, extracts all relevant fields for the target task, and produces a single task-spec.TSK-NNN.yaml that fully defines:

• What the task must produce (output contract)
• What the task requires as input (input contract)
• How completion is evaluated (evaluation criteria)
• How failures are recovered (recovery mapping)
• The exact execution steps (execution plan with EXEC-01 through EXEC-05)

---

Input

Trigger: /new-task <path-to-mission-spec.yaml> <TSK-NNN>

Example:

/new-task .ssdam/media-asset-platform-20260221/output/mission-spec.yaml TSK-001

What the user provides:

• <path-to-mission-spec.yaml> — Path to the mission-spec.yaml generated by new-mission
• <TSK-NNN> — The task ID to spec (e.g., TSK-001, TSK-003)

What the agent reads from files:

• mission-spec.yaml — Primary source for all [DERIVED] fields (see references/input.template.yaml)
• mission-input.yaml — Optional; read from the same workspace's input/ folder; used for tech stack

Pre-conditions (checked by validate.py):

• mission-spec.yaml is valid YAML
• mission-spec.yaml.mission_spec.self_validation.passed: true
• Target TSK-NNN exists in mission-spec.yaml tasks
• Target task initial_state: PENDING

---

PRE-EXECUTION

Before generating anything, run the pre-flight validator:

python3 templetes/new-task/scripts/validate.py <mission-spec-path> <TSK-NNN>

If exit code = 0 (pass or warnings only): Proceed. Show any warnings to the user, then continue.

If exit code = 1 (hard errors): Check the error list:

• If the errors contain only [TECH_STACK_UNDEFINED] and/or [PROJECT_ROOT_UNDEFINED] → run the Tech Stack Recovery Procedure below, then re-run validate.py once. If validate.py still exits 1 after recovery, stop and report to the user.

• If the errors contain any other hard error (not the two above) → Stop immediately. Report all hard errors. Do not proceed until they are fixed.

---

Tech Stack Recovery Procedure

Triggered when validate.py reports [TECH_STACK_UNDEFINED] or [PROJECT_ROOT_UNDEFINED].

Objective: Collect tech stack info from the user, update both mission-input.yaml and mission-spec.yaml, then allow validate.py to pass.

Recovery Step R-1: Inform the user

Show:

⚠️  Tech stack is not defined in mission-spec.yaml or mission-input.yaml.
    The execution plan cannot be generated without this information.
    I will ask you a few questions to resolve this.

Recovery Step R-2: Ask for tech stack (minimal prompts)

Ask the following questions — only ask what is needed based on which error codes fired:

If [TECH_STACK_UNDEFINED]:

Ask 1: "Backend stack? (e.g., Python/FastAPI, Node/Express, Go/Gin, Java/Spring — or 'none' if frontend-only)" Ask 2: "Frontend stack? (e.g., React, Next.js, Vue, Angular — or 'none' if backend-only)" Ask 3: "Database? (e.g., PostgreSQL, MySQL, MongoDB, Redis — or 'none' if no persistence layer)"

Rules:

• If the user answers "none" for backend → set backend_stack: "none" (not "undefined")
• If the user answers "none" for frontend → set frontend_stack: "none" (not "undefined")
• If both backend_stack and frontend_stack are answered (neither is empty), proceed.
• If the user types "skip" or leaves blank → ask once more; if still blank, stop and report.

If [PROJECT_ROOT_UNDEFINED]:

Ask: "What is the absolute path to your project root? (e.g., /Users/dev/my-project)"

Rules:

• Must be an absolute path (starts with / on Unix, C:\ on Windows).
• If the user provides a relative path, resolve it against the current working directory.

Recovery Step R-3: Update mission-input.yaml

Open .ssdam/{id}/input/mission-input.yaml and update the project_context fields with the user's answers. Write the updated file.

# Example of what gets updated:
project_context:
  backend_stack:  "Python/FastAPI"   # ← updated from user answer
  frontend_stack: "React"            # ← updated from user answer
  database:       "PostgreSQL"       # ← updated from user answer
  project_root:   "/Users/dev/app"   # ← updated from user answer (if needed)

Recovery Step R-4: Update mission-spec.yaml

Open .ssdam/{id}/output/mission-spec.yaml and update mission_spec.project_context with the same values:

mission_spec:
  project_context:
    backend_stack:  "Python/FastAPI"
    frontend_stack: "React"
    database:       "PostgreSQL"
    language:       "Python"         # ← infer from backend_stack if reasonable
    project_root:   "/Users/dev/app"

language inference rule: if backend_stack contains "Python" → language: "Python", "Node" or "JavaScript" → language: "JavaScript", "Go" → language: "Go", etc. If inference is ambiguous, ask the user.

Recovery Step R-5: Re-run validate.py

python3 templetes/new-task/scripts/validate.py <mission-spec-path> <TSK-NNN>

• Exit code 0 → Tech stack is now resolved. Continue with Phase 1.
• Exit code 1 → Stop. Report all remaining errors to the user.

---

---

Execution Procedure

Phase 1 — Load & Extract

Step 1 — Load mission-spec.yaml

Read the file at <path-to-mission-spec.yaml>. The root key is mission_spec:. Unwrap it to get the spec object.

Extract and store for use in all subsequent steps:

• spec.metadata → mission-level metadata
• spec.tasks → full task list
• spec.governance → roles, gates, escalation
• spec.task_map → dependency graph
• spec.policies → quality, recovery, traceability

Find the target task: filter spec.tasks where id == TSK-NNN. Store as target_task.

Step 2 — Load mission-input.yaml (optional)

Look for mission-input.yaml at the same workspace's input/ directory:

<same-dir-as-mission-spec>/../input/mission-input.yaml

If it exists and is valid YAML, extract project_context:

• backend_stack
• frontend_stack
• database
• project_root
• language

If the file does not exist or any field is missing, set all tech stack values to "undefined".

---

Phase 2 — Populate Metadata

Step 3 — Derive all metadata fields

Populate task_spec.metadata entirely from mission-spec.yaml. No agent inference:

Field	Source
mission_id	spec.metadata.mission_id
task_id	TSK-NNN (from user command)
task_name	target_task.name
task_owner	spec.governance.roles.task_owners[TSK-NNN]
requirement_ids	target_task.requirements (list of REQ-NNN)
document_id	"task-spec" (fixed)
version	"v0.1.0" (fixed)
created_at	Current UTC timestamp in ISO-8601 (YYYY-MM-DDTHH:mm:ssZ)
schema_version	"1.0.0" (fixed)

---

Phase 3 — Design Purpose & Scope

Step 4 — Write purpose.statement

Derive a single-sentence statement directly from target_task.purpose.

Rules:

• Must state WHAT the task achieves (the deliverable), not HOW.
• Must be testable: a reviewer can read it and decide pass/fail.
• Must not use vague terms ("improve", "enhance", "address").

Example:

"Implement RESTful CRUD API endpoints for the media asset resource, including OpenAPI documentation."

Step 5 — Define scope boundaries

scope_included — List 3–5 items that are explicitly part of this task. Derive from target_task.artifact.description and target_task.purpose.

scope_excluded — List 2–4 items that are explicitly NOT part of this task (guard rails). Derive from adjacent tasks in the dependency graph: what does the next task cover that this task must not touch?

---

Phase 4 — Design Contracts

Step 6 — Write input_contract

Check target_task.dependencies:

• If empty or null → single entry: input_item: "none", artifact_id: "none", contract_requirement: "none"
• For each dependency TSK-DEP:
  • input_item: describe the concrete deliverable from TSK-DEP
  • artifact_id: ART-TSK-DEP-NN — look up from the already-generated task-spec for TSK-DEP; if not yet generated, use ART-TSK-DEP-?? and add a soft warning
  • contract_requirement: verifiable condition the input must satisfy

Step 7 — Write output_contract

Expand every item in target_task.artifact.description into one or more concrete contract entries.

For each entry:

• output_artifact: short name (e.g., "API implementation", "OpenAPI spec")
• artifact_id: ART-TSK-NNN-NN — assign NN starting at 01, incrementing per artifact
• contract_specification: concrete, verifiable description (format, structure, content)

Rules (from references/rules.md Section 3):

• No vague language in contract_specification
• Every deliverable in artifact.description must have at least one entry
• If artifact.description is underspecified, make it concrete

---

Phase 5 — Design Evaluation

Step 8 — Write evaluation_criteria

Generate at least 3 criteria. Each criterion must be binary PASS/FAIL.

For each criterion:

• criterion_id: CRIT-01, CRIT-02, ... (sequential, no gaps)
• criterion: specific, testable condition (no forbidden terms)
• policy_reference: QPOL-NN from spec.policies.quality
• measurement_method: exactly how it is measured (automated test / manual verification / file existence check / CLI command)
• pass_threshold: quantitative value

Coverage guidance:

• At least one criterion per output_contract entry
• Include structural checks (file exists, schema valid) and behavioral checks (tests pass, API responds)
• If spec.constraints.performance is defined, include a performance criterion
• If spec.constraints.security is defined, include a security criterion

Step 9 — Write checkpoint

Derive all fields from mission-spec:

Field	Source
checkpoint_id	target_task.checkpoint.id (must be CP-TSK-NNN)
gate_id	spec.governance.gates[task_id == TSK-NNN].id (must be GATE-TSK-NNN)
gate_type	Agent judgment: automatic / human / hybrid (see rules Section 5)
final_approver	spec.governance.roles.reviewers
evaluation_policy_references	All QPOL-NN from spec.policies.quality
recovery_policy_reference	RPOL-NN from spec.policies.recovery

Step 10 — Write recovery_mapping

Generate exactly 3 entries (one per failure type):

1. Transient failure → retry, max_retry from mission-spec recovery strategies
2. Partial implementation failure → partial_fix, max_retry from mission-spec
3. Structural failure → task_redesign, max_retry always 0

For each entry:

• failure_type: concrete description (e.g., "Environment setup failure — dependency unavailable")
• rpol_reference: RPOL-NN from spec.policies.recovery
• max_retry: derive from spec.policies.recovery.strategies.max_attempts; default 3 if undefined
• recovery_strategy: retry | partial_fix | task_redesign
• escalation_trigger: "After N FAILs or M time blocked, escalate to <escalation_target>"
  • N: spec.governance.escalation.repeated_failure_threshold
  • M: spec.governance.escalation.blocked_duration_threshold
  • <escalation_target>: spec.governance.escalation.escalation_target

---

Phase 6 — Design Execution Plan

Step 11 — Determine applicable execution steps

Evaluate which of the seven default steps apply to this task. Steps must be included in chain order — skipping a prerequisite is forbidden (e.g., no schema-design without data-modeling).

exec_type	exec_name	Include if…	Prerequisite
architecture-design	Architecture Design	Always — mandatory first step	—
data-modeling	Data Modeling	Task involves new DB entities or relationships	architecture-design
schema-design	Schema Design	Task involves DB schema creation or changes	data-modeling
backend-design	Backend Design	Task produces server-side code, APIs, or services	architecture-design
backend-implementation	Backend Implementation	backend-design is included	backend-design
frontend-design	Frontend Design	Task produces UI components, pages, or client-side code	architecture-design
frontend-implementation	Frontend Implementation	frontend-design is included	frontend-design

Skip inapplicable steps. Renumber remaining steps consecutively starting at EXEC-01 (no gaps).

Step 12 — Write execution_plan.tech_stack

Populate from mission-input.yaml project_context (Step 2):

• backend: backend_stack value, or "undefined"
• frontend: frontend_stack value, or "undefined"
• database: database value, or "undefined"
• project_root: project_root value, or "undefined"

Step 13 — Write each execution step

For each included step, populate:

Field	Content
exec_id	EXEC-NN (consecutive, starting at EXEC-01)
exec_name	Standard name from the default flow
exec_type	architecture-design | data-modeling | schema-design | backend-design | backend-implementation | frontend-design | frontend-implementation
description	What the agent does in this step — specific enough to execute without other context
target_artifacts	Which artifact_id values from output_contract this step contributes to. Rule: architecture-design always targets ALL artifact_ids from output_contract (it is the foundation for every downstream artifact). All other steps target only the artifact_ids they directly produce.
dependencies	[] for first step; direct predecessor exec_id list for others
output_files	Top-level dir or file paths (use {project_root} if project_root is undefined)
tech_context	Technology context for this step (from tech_stack + task requirements)
acceptance_criteria	Verifiable completion check (file exists / command exits 0 / etc.)

Step dependency rules:

• architecture-design: dependencies [] (always first)
• data-modeling: depends on architecture-design step
• schema-design: depends on data-modeling step
• backend-design: depends on schema-design if included; otherwise on architecture-design
• backend-implementation: depends on backend-design step
• frontend-design: depends on backend-design if included; otherwise on architecture-design
• frontend-implementation: depends on frontend-design step

Parallel execution note: When both backend-implementation and frontend-design are included, these two steps — and only these two — can run in parallel, because frontend-design depends on backend-design (not on backend-implementation). The dependency split happens at backend-design: both backend-implementation and frontend-design wait for it, then proceed independently. Record this in flow.parallel_groups per the algorithm in Step 14.

Step 14 — Write execution_plan.flow and execution_handoff

flow.default_sequence: All included exec_id values in topological order (same order as steps).

flow.parallel_groups: Compute using the following algorithm — do NOT default to [] without checking.

Parallel Group Algorithm:

1. For each included step, record its direct dependencies (already set in Step 13).
2. Compute transitive closure: for each step X, the full set of steps that must complete before X starts (follow dependency chains recursively).
3. Two steps A and B can execute in parallel if and only if:
   • A is NOT in B's transitive closure, AND
   • B is NOT in A's transitive closure.
4. Collect all maximal sets of steps where every pair satisfies the condition above. Only include sets with 2 or more steps.
5. Write each set as one entry in parallel_groups.

Standard pattern in SSDAM execution plans:

When both backend-implementation and frontend-design are present and frontend-design depends on backend-design (not on backend-implementation):

EXEC-?? (backend-design)
  ├─→ EXEC-?? (backend-implementation)   ← no dependency between these two
  └─→ EXEC-?? (frontend-design)          ← both depend only on backend-design
        └─→ EXEC-?? (frontend-implementation)

→ backend-implementation and frontend-design can run in parallel. → Set parallel_groups: [["<backend-implementation exec_id>", "<frontend-design exec_id>"]]

Concrete example (5-step backend+frontend plan without data chain):

steps:
  - exec_id: EXEC-01  # architecture-design  deps: []
  - exec_id: EXEC-02  # backend-design        deps: [EXEC-01]
  - exec_id: EXEC-03  # backend-implementation deps: [EXEC-02]
  - exec_id: EXEC-04  # frontend-design       deps: [EXEC-02]   ← depends on EXEC-02, NOT EXEC-03
  - exec_id: EXEC-05  # frontend-implementation deps: [EXEC-04]

# EXEC-03 transitive closure: {EXEC-01, EXEC-02}
# EXEC-04 transitive closure: {EXEC-01, EXEC-02}
# EXEC-03 not in EXEC-04's closure, EXEC-04 not in EXEC-03's closure → PARALLEL

flow:
  default_sequence: ["EXEC-01", "EXEC-02", "EXEC-03", "EXEC-04", "EXEC-05"]
  parallel_groups:  [["EXEC-03", "EXEC-04"]]

When parallel_groups stays []:

• Only one chain is present (e.g., pure backend task with no frontend steps)
• All steps form a strict linear sequence (each step depends on the immediately preceding one)
• frontend-design directly depends on backend-implementation (not just backend-design)

execution_handoff:

• next_element: "execution" (fixed)
• execution_unit: "step" (fixed)
• total_steps: exact count of included steps in execution_plan.steps

---

Phase 7 — Handoff

Step 15 — Write handoff

Field	Source
next_task_id	Find edge in spec.task_map.dependency_graph where from == TSK-NNN; use to as next task. If no outgoing edge, use "END".
handoff_artifacts	All artifact_id values from output_contract
handoff_evidence	One EVD-TSK-NNN-NN per evaluation criterion (placeholder; actual evidence created during execution)

---

Phase 8 — Self-Validation

Step 16 — Run all self-validation checks

Hard checks (stop if any fail — do not write the file):

#	Check	Verification
H-01	Target task initial_state == PENDING	Field check
H-02	checkpoint_id matches target_task.checkpoint.id	String match
H-03	gate_id matches spec.governance.gates[task_id == TSK-NNN].id	String match
H-04	All QPOL-NN in evaluation_policy_references exist in spec.policies.quality	Reference check
H-05	RPOL-NN in recovery_policy_reference exists in spec.policies.recovery	Reference check
H-06	At least 1 output_contract entry	Count ≥ 1
H-07	At least 3 evaluation_criteria entries	Count ≥ 3
H-08	At least 3 recovery_mapping entries	Count ≥ 3
H-09	All exec_id values are unique	No duplicates
H-10	exec_id sequence starts at EXEC-01 with no gaps	Sequence check
H-11	total_steps equals count of steps in execution_plan.steps	Integer match
H-12	Every dependency in target_task.dependencies has an input_contract entry	Coverage check
H-13	output_contract fully covers target_task.artifact.description	Content match

Soft checks (write spec with passed: true, but populate failed_checks):

Check	Warning message format
Any field contains literal "TBD"	"WARNING: Field <field_path> is TBD. Resolve before executing this task."
Any tech stack field is "undefined"	"WARNING: Tech stack undefined. Populate mission-input.yaml project_context before executing EXEC steps."
project_root is "undefined"	"WARNING: project_root undefined. output_files use placeholder {project_root}."
Any artifact_id in input_contract contains "??"	"WARNING: input_contract artifact_id for predecessor TSK-NNN not resolved. Generate that task-spec first."

Output rule:

• All hard checks pass → self_validation.passed: true, proceed to Step 17
• Any hard check fails → report failures to user, do not write any file
• Only soft warnings → self_validation.passed: true, populate failed_checks, proceed to Step 17

---

Phase 9 — Output

Step 17 — Write task-spec.TSK-NNN.yaml

Write the fully assembled spec to:

.ssdam/{id}/output/task-spec.TSK-NNN.yaml

Where {id} is derived from the path to mission-spec.yaml (the workspace folder name). Where NNN is the 3-digit task number from the user command.

Use the structure defined in references/output.template.yaml.

---

POST-EXECUTION

After writing the file, report to the user:

1. Output location: full path to the generated file
2. Summary: task name, number of output artifacts, number of execution steps
3. Warnings: any soft check warnings from self_validation.failed_checks
4. Next action: whether more tasks remain to be spec'd (from handoff.next_task_id)

Report format:

✓ task-spec.TSK-NNN.yaml written to:
  .ssdam/{id}/output/task-spec.TSK-NNN.yaml

Task : TSK-NNN — {task_name}
Artifacts : {N} output artifacts ({ART-TSK-NNN-01}, ...)
Exec steps: {N} ({EXEC-01} → {EXEC-NN})

[Warnings if any]

Next: run /new-task ... TSK-MMM to spec the next task,
      or begin execution of task-spec.TSK-NNN.yaml.

---

Error Handling

Error	Action
validate.py reports hard errors	Stop. Show all errors. Do not generate task-spec.
mission-spec.yaml not found	Stop. Report path error to user.
Target TSK-NNN not in mission-spec	Stop. List available task IDs.
Target task initial_state != PENDING	Stop. Explain that only PENDING tasks can be spec'd.
Hard check fails during self-validation (Step 16)	Stop. Report which checks failed. Do not write file.
artifact.description is empty or undefined	Stop. Report that the task has no deliverable defined. Ask user to fix mission-spec.
Predecessor task-spec not yet generated	Proceed with ART-TSK-NNN-?? placeholders. Add soft warning. Do not stop.
mission-input.yaml not found	Proceed with "undefined" tech stack. Add soft warning. Do not stop.