feat: define YAML team profiles

Author: Howe829

plugins/tfd/examples/project-tfd/manifest.yaml

@@ -0,0 +1,3 @@
+version: 1
+teams:
+  - product-team

plugins/tfd/examples/project-tfd/product-team/members/alice.yaml

@@ -0,0 +1,7 @@
+display_name: Alice
+responsibility: Implement the agreed product scope
+expected_output: A runnable and verified result
+model: gpt-5.6-sol
+skills:
+  - superpowers:test-driven-development
+agency_role: backend-architect

plugins/tfd/examples/project-tfd/product-team/members/bob.yaml

@@ -0,0 +1,7 @@
+display_name: Bob
+responsibility: Independently review the delivered candidate
+expected_output: A PASS, BLOCKER, or UNVERIFIED verdict with evidence
+model: gpt-5.6-sol
+skills:
+  - superpowers:verification-before-completion
+agency_role: code-reviewer

plugins/tfd/examples/project-tfd/product-team/team.yaml

@@ -0,0 +1,6 @@
+name: product-team
+purpose: Deliver a reviewed product change
+members:
+  - alice
+  - bob
+trace: delivery_receipt

plugins/tfd/scripts/test_tfd_skill_contract.py

@@ -11,6 +11,14 @@
 SKILL_ROOT = SKILLS_ROOT / "using-tfd"
 SKILL_PATH = SKILL_ROOT / "SKILL.md"
 AGENT_METADATA_PATH = SKILL_ROOT / "agents" / "openai.yaml"
+EXAMPLE_ROOT = PLUGIN_ROOT / "examples" / "project-tfd"
+MEMBER_FIELDS = {
+    "display_name",
+    "responsibility",
+    "expected_output",
+    "model",
+    "skills",
+}
 
 REMOVED_PATHS = (
     "skills/team",
@@ -69,6 +77,36 @@ def test_skill_stays_within_line_budget(self) -> None:
         line_count = len(SKILL_PATH.read_text(encoding="utf-8").splitlines())
         self.assertLessEqual(line_count, 250)
 
+    def test_example_team_graph_is_valid(self) -> None:
+        manifest = yaml.safe_load(
+            (EXAMPLE_ROOT / "manifest.yaml").read_text(encoding="utf-8")
+        )
+        self.assertEqual(manifest, {"version": 1, "teams": ["product-team"]})
+
+        team_root = EXAMPLE_ROOT / "product-team"
+        team = yaml.safe_load(
+            (team_root / "team.yaml").read_text(encoding="utf-8")
+        )
+        self.assertEqual(
+            set(team),
+            {"name", "purpose", "members", "trace"},
+        )
+        self.assertEqual(team["name"], team_root.name)
+        self.assertEqual(team["trace"], "delivery_receipt")
+
+        for member_id in team["members"]:
+            with self.subTest(member=member_id):
+                profile = yaml.safe_load(
+                    (team_root / "members" / f"{member_id}.yaml").read_text(
+                        encoding="utf-8"
+                    )
+                )
+                self.assertTrue(MEMBER_FIELDS <= profile.keys())
+                self.assertTrue(
+                    profile.keys() <= MEMBER_FIELDS | {"agency_role"}
+                )
+                self.assertTrue(profile["skills"])
+
     def test_removed_v2_skill_and_scanner_surfaces_are_absent(self) -> None:
         present = [
             relative

plugins/tfd/skills/using-tfd/SKILL.md

@@ -1,173 +1,140 @@
 ---
 name: using-tfd
-description: Use when the user explicitly requests TFD or a development task may benefit from specialized agents, separated context, independent review, or durable cross-session evidence.
+description: Use when the user requests TFD or a development requirement may benefit from multiple professional responsibilities, separated context, or independent review.
 ---
 
 # Using TFD
 
-TFD is selective team orchestration for development work. This is its single
-normative user Skill. Its core rule is: use the smallest structure whose
-quality, focus, or risk-reduction benefit exceeds its coordination cost.
+TFD forms the minimum useful team for one bounded development requirement.
+Its value is alignment, model-role fit, and context isolation—not durable
+workflow machinery.
 
-The workflow order is mandatory:
+Follow this order:
 
 ```text
-SUITABILITY -> ALIGN -> TEAM -> EXECUTE -> REVIEW -> DELIVER
+SUITABILITY -> PLAN -> SELECT -> EXECUTE -> REVIEW -> DELIVER
 ```
 
 ## SUITABILITY
 
-Decide one route before forming a team or touching TFD state:
-
-- `SOLO`: ordinary single-Agent work; no `.tfd` creation or write.
-- `TFD_SESSION`: the default TFD route; state exists only in this session.
-- `TFD_HIGH_ASSURANCE`: an explicitly approved upgrade that may use durable
-  state through `tfd_state`.
-
-Choose TFD only when all of these hold:
-
-1. The Task has at least two non-ceremonial professional responsibilities with
-   separable outputs or decisions, **or** its risk requires a producer/reviewer
-   split.
-2. Relevant context can be separated by responsibility.
-3. The expected quality, focus, or risk-reduction benefit is greater than
-   coordination and handoff cost.
-
-If any condition fails, recommend `SOLO` and do not create or write `.tfd`.
-An explicit request to "use TFD" requests this decision; it does not predetermine
-the answer. If the user still forces TFD, first disclose the coordination cost,
-then use the smallest session-scoped team that preserves real responsibility
-separation.
-
-High assurance is justified only by reliable cross-session continuation,
-durable decision/handoff/review evidence, multi-day or materially concurrent
-work, elevated change risk, or an explicit request for durable local state.
-Even then, remain `TFD_SESSION` until the user explicitly approves the named
-Task's durable-state upgrade and scope. Existing `.tfd` content, urgency, sunk
-cost, or an authority's preference never activates or authorizes durable state.
-Do not inspect, create, or update it merely because it exists.
-
-| Pressure rationalization | Required response |
-| --- | --- |
-| "TFD was requested, so a full team is mandatory." | Run the gate; unsuitable work remains `SOLO`. |
-| "The Workspace already exists, so use it now." | Stay session-only until explicit high-assurance approval. |
-| "The deadline or manager makes the normal boundary optional." | Deadlines and titles do not expand authority. |
-
-These claims are red flags: stop before team formation, state access, or an
-external action and return to the applicable decision above.
-
-## ALIGN
-
-State one bounded alignment envelope:
-
-- outcome;
-- acceptance conditions;
-- allowed scope and actions;
-- prohibited scope and actions;
-- consequential and external approval boundaries.
-
-Obtain one kickoff approval for that exact outcome, boundary, acceptance, and
-proposed team before team execution. Routine reversible local work inside the
-approved boundary needs no repeated transition approval. A kickoff or
-high-assurance approval never approves external or high-risk actions.
-
-Reject secrets, credentials, tokens, private keys, or other secret values.
-Never put them in prompts, Task Briefs, handoffs, TFD state, logs, or evidence.
-Use sanitized references or a user-performed step instead. Never request full
-conversations or hidden reasoning as evidence.
-
-## TEAM
-
-Choose the minimum sufficient responsibilities. A Coordinator is an
-orchestration function, not a ceremonial role. Add a member only when it owns a
-separable output/decision or supplies the required independent risk gate.
-
-For each member record responsibility, expected output, acceptance condition,
-required inputs, handoff recipient, selected callable model, and selection
-basis. Select from current-Task evidence and current live host metadata for
-callable backends only:
-
-- do not scan, enumerate, or score the account-wide model catalog;
-- do not infer capability or quality from a model name;
-- if role-fit evidence is absent, label it `UNVERIFIED`;
-- if an exact requested model is unavailable, do not silently substitute it;
-  use a disclosed callable fallback only when the user did not require the
-  exact model.
-
-Model metadata proves callability only. Focus comes from recipient-specific
-briefs; logical tool or Skill restrictions do not prove host-level isolation,
-invisible capabilities, or operating-system enforcement.
+Choose `SOLO` unless the requirement has either:
 
-## EXECUTE
+- two or more separable, non-ceremonial professional responsibilities; or
+- enough risk to require a producer and an independent reviewer.
 
-Issue each member one focused Task Brief in this shape:
-
-```yaml
-outcome: shared result
-scope: allowed target and actions
-prohibitions: forbidden targets and actions
-acceptance: observable checks
-role: assigned responsibility
-model: current callable model
-model_selection_basis: task evidence and live-host metadata
-required_inputs: only what this role needs
-expected_output: artifact or decision
-required_evidence: checks and references
-next_handoff: named recipient and exact next action
-```
+The benefit must exceed coordination cost. An explicit TFD request still goes
+through this check. For `SOLO`, do not inspect or write `.tfd` and do not create
+team members.
 
-Do not forward the full conversation, unrelated project material, another
-member's private brief, secrets, credentials, or hidden reasoning. Share only
-the outcome plus the context and interfaces needed for the assigned
-responsibility.
+Project setup is separate from execution. When asked to configure TFD for a
+project, create only team profiles; do not create Agents. A requirement may
+activate a team later, within its current Codex session.
 
-Every handoff contains only the completed result, artifact or decision
-references, checks performed, unresolved risks, and exact next action. The
-Coordinator may integrate bounded outputs but cannot independently review an
-output it produced. A blocker returns only the named scope for repair.
+## PLAN
 
-## REVIEW
+State a lightweight development plan with:
 
-The reviewer must be a participant distinct from the responsible producer.
-Bind review to one immutable, reproducible candidate reference, such as a Git
-commit or candidate-manifest digest, plus the relevant acceptance conditions
-and evidence.
+- bounded outcome and acceptance conditions;
+- allowed and prohibited scope;
+- separable responsibilities;
+- verification and independent-review needs.
 
-The reviewer reports `PASS`, `BLOCKER`, or `UNVERIFIED` and cites observed
-evidence. A blocker names its repair scope and returns that scope to execution;
-it does not open an unlimited loop. Any changed candidate needs a new reference
-and a new independent review. Review of a moving target, self-review, or a
-verdict without candidate-bound evidence is not acceptance.
+Normal reversible work inside the requested scope needs no extra TFD approval.
+Deployment, publication, push, external messages, destructive changes, paid
+resources, privileges, and scope expansion retain their normal approval gates.
 
-## DELIVER
+## SELECT
+
+When a team is justified, read project-local configuration in this order:
 
-Reduce evidence without promotion:
+1. `.tfd/manifest.yaml`;
+2. the listed teams' `team.yaml` files;
+3. only the selected members' files under `members/`.
 
-- `PASS`: directly observed evidence satisfies the named check.
-- `BLOCKER`: a named condition prevents safe completion.
-- `UNVERIFIED`: required evidence was not observed.
+The manifest contains only `version: 1` and team directory IDs. Select exactly
+one configured team whose purpose fits the plan, then the minimum member subset
+whose responsibilities cover it. Never combine teams for one requirement. A
+recurring cross-functional composition must be its own configured team.
 
-Report these claims separately:
+Each team directory contains:
 
 ```text
-IMPLEMENTED: artifacts or decisions that exist
-VERIFIED: checks actually run and their candidate-bound results
-ACCEPTED: named reviewer and user acceptances actually received
-UNVERIFIED: runtime, deployment, human, model-fit, or value axes not observed
-CONTRIBUTIONS: each member's attributable result
-NEXT: exact approval or action still required
+team.yaml
+members/<member-id>.yaml
+receipts/                 # optional
 ```
 
-Automated checks cannot promote human, runtime, deployment, or user acceptance.
-Do not call `UNVERIFIED` successful delivery.
+`team.yaml` has `name`, `purpose`, `members`, and optional
+`trace: delivery_receipt`. Each member file has exactly these required fields:
+
+- `display_name`
+- `responsibility`
+- `expected_output`
+- `model`
+- `skills`
+
+`agency_role` is optional provenance from a one-time agency-agents reference.
+It is not a runtime dependency, persona sync, installer, or orchestrator.
+
+Before creating any member:
+
+1. require its exact `model` among the choices explicitly exposed by the
+   current `spawn_agent` runtime;
+2. require every configured Skill by exact name among locally installed Codex
+   Skills;
+3. stop and report the member and missing dependency if either check fails.
+
+Do not scan an account model catalog, cache availability, infer capability from
+a model name, install a Skill, repair a profile, substitute a model, or fall
+back. If exact-model Agent initialization fails, stop and report it.
+
+## EXECUTE
+
+Create only the selected members, with their exact configured models. Give each
+member a focused brief containing:
+
+- shared outcome and acceptance conditions;
+- its configured responsibility and expected output;
+- allowed scope and prohibitions;
+- only the inputs needed for its responsibility;
+- its configured Skills as the required working method;
+- required verification and next handoff.
+
+Do not forward unrelated project context, secrets, credentials, full
+conversations, or hidden reasoning. A Skill list scopes the brief; it does not
+prove the host hides other Skills or provides operating-system isolation.
+
+Handoffs contain only the result or decision, artifact reference, checks,
+unresolved items, and next action.
+
+## REVIEW
+
+Use a reviewer distinct from the producer when the plan requires independent
+review. Bind the review to an immutable candidate reference and its acceptance
+conditions. The verdict is `PASS`, `BLOCKER`, or `UNVERIFIED`, with observed
+evidence.
+
+A blocker returns only its named repair scope. A changed candidate needs a new
+reference and review. Automated checks do not become human, runtime,
+deployment, or user acceptance.
+
+## DELIVER
+
+Report the delivered result, verification, review, member contributions,
+unresolved items, and any real next gate. End the active team with the session;
+do not persist Tasks, progress, events, handoffs, prompts, conversations, or
+recovery state.
+
+If and only if the selected team sets `trace: delivery_receipt`, write one
+short Markdown receipt under `<team>/receipts/` after final delivery. Name it
+`YYYY-MM-DD-<requirement-slug>.md` and include only:
 
-Deployment, publishing, push, external messaging, deletion, paid resources,
-privileged commands, and scope expansion each retain a separate explicit
-approval gate. Deadline, manager instruction, kickoff approval, stored actor
-ID, or high-assurance activation does not supply that authority.
+- delivered outcome;
+- selected team and members, with one contribution each;
+- result reference;
+- verification and independent-review result;
+- unresolved items.
 
-TFD user and actor identifiers provide strict attribution inside TFD only.
-They are not operating-system authentication. Logical allowlists and focused
-briefs are not host isolation. Never claim OS-authenticated identity, host-level
-Skill/tool isolation, or model quality without direct runtime evidence; keep
-those axes `UNVERIFIED`.
+The receipt is a human-readable trace, not authority or resumable state. Do not
+write process logs, prompts, reasoning, intermediate handoffs, progress,
+events, token/timing data, raw outputs, diffs, an index, or management scripts.