New Task

File Paths Reference

Skill Definition Files (read-only)

Runtime Files (created per task)

{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

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:

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:

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).

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:

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

Phase 8 — Self-Validation

Step 16 — Run all self-validation checks

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

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

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