sw-team-orchestration

name	sw-team-orchestration
description	Generic orchestration protocol for SW-TEAM-style multi-phase, gated, KB-backed, artefact-logged projects. Covers gate pattern, subagent invocation rules, KB protocol, artefacts.jsonl protocol, loop-back handling, and session startup protocol. Domain-agnostic — contains no project-specific vocabulary. Load alongside a domain-specific SKILL (e.g., {domain}-domain) in every orchestrator agent.

SW-TEAM Orchestration Protocol

This SKILL encapsulates the protocol for running any SW-TEAM-style multi-phase project. It contains zero domain vocabulary. An agent loading this SKILL knows how to orchestrate — not what the phases contain. Domain knowledge lives in a separate domain SKILL (see ## ADAPT — Phase manifest source).

---

FIXED — Framework Tokens

These tokens are the canonical single source of truth for cross-SKILL communication. Domain SKILLs must reference these definitions rather than defining tokens inline.

Token	Semantic definition
[APPROVED]	Human has explicitly approved the current phase gate. Advancement is permitted.
[REJECTED]	Human has explicitly rejected the current phase gate. A loop-back or corrective action is required.
[READY]	Human has confirmed a prerequisite condition (e.g., environment setup complete). The agent may proceed.
[LOCKED]	A KB entry has been reviewed and finalised by the orchestrator. It cannot be modified.
[PROPOSED]	A KB entry has been written by a worker agent and awaits orchestrator review and locking.
[DECISION]	A point requiring explicit human confirmation before the project advances. Record the outcome in the KB.
LOOP_BACK_REQUESTED: <phase> — <reason>	A worker agent has detected a condition requiring re-execution of a prior phase. Present this flag and its reason to the user; await [APPROVED] before re-invoking.
[XKB-NNN]	KB entry ID format. X = prefix letter(s) defined by the domain SKILL; NNN = zero-padded sequential integer within each KB file. Example: [BKB-003].
artefact_NNN	Artefact manifest ID format. NNN = zero-padded sequential integer. Read the last line of artefacts.jsonl to determine the next N.

---

FIXED — Gate pattern

A gate is the checkpoint that must pass before advancing to the next phase.

Checkpoint list format:

- [ ] <criterion>
- [ ] <criterion>

Advancement rule: All checkboxes must be ticked and the human must have provided an explicit [APPROVED] token before the next phase begins. A partially filled gate is not a passed gate.

Human approval token: [APPROVED] (definition above in Framework Tokens). Wait for this exact token in the human's message. Do not infer approval from positive sentiment alone.

Rejection handling: If the human provides [REJECTED], do not advance. Present the rejection reason and await further instructions. A loop-back may follow.

---

FIXED — Subagent invocation rules

These rules apply to every worker agent invocation, regardless of domain.

1. Sequential only. Never invoke two worker agents concurrently. One invocation must complete and return a result summary before the next begins. This prevents concurrent writes to artefacts.jsonl.

2. Self-contained prompts. Worker agents have no access to this session's conversation history. Every invocation prompt must include, in full:

   • The relevant Specification file path(s) and their complete content (paste verbatim)
   • The relevant KB section excerpt (paste the text — do not reference by line number)
   • All required input artefact paths (absolute paths resolved from <project_root>)
   • All expected output artefact paths
   • A clear statement of the deliverables and the gate condition

3. Implicit reference prohibition. The following patterns must never appear in invocation prompts:

   • "See the spec file" — instead, paste the full text
   • "Use the confirmed values from the KB" — instead, paste the KB entry text
   • "Check the previous model" — instead, paste the relevant artefact summary

4. Never modify worker outputs. If a worker agent produces a file, do not edit it. Present it to the user as-is and await [APPROVED] or a loop-back decision.

5. After every invocation: append all artefacts listed in the worker's result summary to the manifest via {package}.utils.manifest.append_artefact(). Lock all KB entries proposed in the result summary after reviewing them.

---

FIXED — KB protocol

• Read before acting. Before any phase, read the relevant KB sections for this project.
• Review before locking. After any worker agent returns, review proposed KB entries for correctness before locking them. Locking is irreversible.
• ID format. Entries follow the format [XKB-NNN] (see Framework Tokens above). The prefix X is defined by the domain SKILL. Check that the next sequential ID is not already used before writing.
• Orchestrator-only locking. Only the orchestrator may mark an entry [LOCKED]. Worker agents propose entries with [PROPOSED]; the orchestrator changes to [LOCKED] after review.
• No deletion. KB entries are never deleted. If a finding is superseded, append a new entry referencing the old one and explaining the update.

---

FIXED — artefacts.jsonl protocol

• Append only. Call {package}.utils.manifest.append_artefact() for every artefact. Never write to artefacts.jsonl directly.
• Never delete or modify existing lines.
• id format: artefact_NNN (see Framework Tokens above) — read the last line of the manifest to determine N, increment by 1. If the file is empty or does not exist, start at artefact_001.
• created_at: always UTC, ISO 8601 format YYYY-MM-DDTHH:MM:SSZ.
• run_id and artifact_group_id: set to null for artefacts that do not have them. Never omit these fields.

---

FIXED — Loop-back handling

A loop-back is triggered when a worker agent raises LOOP_BACK_REQUESTED: <phase> — <reason> (token format defined in Framework Tokens above).

Protocol:

1. Present the full flag text and the reason to the user.
2. Await [APPROVED] before re-invoking. Do not re-invoke on user silence.
3. Once approved: create a new versioned ID for the affected artefact. ID format and naming conventions are defined in the domain SKILL — consult the domain SKILL's phase inventory for the correct ID type and format.
4. Re-invoke the worker agent with:
   • The loop-back context explicitly included in the invocation prompt
   • The prior ID that failed
   • The reason for the loop-back
   • The approved changes to the spec

---

FIXED — Session startup protocol

At the start of every session, follow these steps in order (steps 1–4 below). Step 0 (environment health check) is domain-specific and is defined in the agent body itself, because it must run before any SKILL is loaded.

1. Read copilot-instructions.md to confirm <project_root> for this workspace.
2. Check whether <project_root>/artefacts.jsonl exists.
   • If yes: the project is in progress. Read the last 5 lines to confirm the current phase.
   • If no: this is a fresh project. Proceed to Phase 1 initialisation as defined in the domain SKILL.
3. Check whether the KB files for this project type exist (KB file paths defined in the domain SKILL).
   • If no: create them by copying the KB starter templates from the templates directory, substituting project-specific placeholder values.
4. Greet the user with a one-sentence project status summary.

---

ADAPT — Project root

Resolved at session startup from copilot-instructions.md:

<project_root> = {{PROJECT_ROOT}}

---

ADAPT — Phase manifest source

The domain SKILL that defines the phase list, action sequences, gate checklists, and handoff prompt templates for this project type:

{{DOMAIN_SKILL_PATH}}

---

ADAPT — KB file set

KB files for this project type (names and paths filled from the domain SKILL):

{{KB_FILE_SET}}