sw-team-architect

name	sw-team-architect
description	Methodology for producing and reviewing design briefs for any SW-TEAM framework build. Loaded by the SW-TEAM-Architect agent at session startup. Covers design brief structure (Sections A–D), function design rules, SKILL.md scaffold rules, agent prompt architecture rules, design review workflow, and seven non-negotiable design constraints. Domain-agnostic — contains no project-specific vocabulary. Load alongside a domain-context SKILL (e.g., {domain}-builder-context) in the Architect agent.
user-invocable	false

SW-TEAM Architect — Methodology SKILL

Audience: SW-TEAM-Architect agent only. Domain vocabulary: Zero — no package names, no project-specific nouns, no track names. Load alongside: <domain>-builder-context/SKILL.md for domain-specific values.

---

FIXED — Design Brief Structure

A design brief is a single markdown document stored at:

docs/design_briefs/<phase-slug>_design_brief.md

It contains up to four sections depending on what the phase delivers:

Section	Covers	Required when
A: Function Signatures	Public API for every {package}/ function the phase delivers	Any {package}/ function is a deliverable
B: Spec Template Fields	Field list, placeholder format, and status lifecycle for spec templates	Any spec template is a deliverable
C: SKILL.md Scaffold Layout	FIXED section content, ADAPT section markers, Layer A call list, validation-sandwich	Any SKILL.md file is a deliverable
D: Agent Prompt Architecture	Frontmatter fields, tool list, handoff prompts, system prompt structure	Any .agent.md file is a deliverable

Section A format — one table row per function:

Symbol	Module path	Signature	Returns	Raises	Edge cases	Test fixture
function_name()	{package}.module.submodule	(arg: type, ...) -> type	Description	ErrorType: condition	empty list, NaN	fixture variable name

Section B format — one table row per field:

Field name	Required	Placeholder format	Description
scope_id	✅	<scope_NNN_YYYYMMDD>	Identifier for this top-level project scope

Section C format — one block per SKILL.md:

SKILL: <skill-name>
FIXED sections: [list of section names with content summaries]
ADAPT sections: [list of section names with what the agent fills and from which source]
Layer A calls: [full.module.function() for every package call in the scaffold]
Validation sandwich: [FIXED pre-validation → ADAPT transform → FIXED post-validation]
Output paths: [list of files the scaffold writes]

Section D format — one block per agent:

Agent: <agent-name>
Frontmatter: name, description, tools=[...], model=..., user-invocable=true/false
Handoffs: [label, target-agent, prompt-summary (must be self-contained)]
System prompt structure: role → startup → references → responsibilities → workflows → rules
Special constraints: [e.g., "must declare agents: [WorkerA, WorkerB]" for orchestrators]

---

FIXED — Function Design Rules

Every {package}/ function delivered by the Architect's design brief must satisfy these rules. Violations in Section A are design defects — escalate before implementation.

1. Stateless: no file I/O, no spec reading, no print(), no global mutable state. If a function needs data from a spec, the caller passes it as an argument.
2. Single-responsibility: one function, one well-defined transformation. Orchestration belongs in SKILL.md scaffolds, not in {package}/ functions.
3. Fully type-hinted: all parameters and return values annotated. Use pd.DataFrame, list[str], dict[str, float], Path, etc.
4. Defensive: raise specific exceptions on invalid input.
   • Empty collection → ValueError with message explaining what was empty
   • Wrong type → TypeError with type and parameter name
   • Out-of-range value → ValueError with range and received value
5. Testable: every function must have at least one test case per design brief edge case. The test must use the domain validation fixture (from domain-context SKILL §FIXED — Validation scenario).
6. No cross-track contamination: functions for one modelling track must not import from another track's module. Track isolation is enforced at the import level.
7. Docstring required: Google-style, with Args:, Returns:, Raises: sections.

---

FIXED — SKILL.md Scaffold Rules

Every SKILL.md designed in Section C must satisfy:

1. FIXED/ADAPT mandatory: every scaffold must have at least one ## FIXED section and at least one ## ADAPT section. A scaffold with no ADAPT is hardcoded; a scaffold with no FIXED is an unstructured prompt.

2. Validation sandwich: scaffold must follow the pattern:

   ## FIXED — Validate inputs         (check spec values, column presence)
   ## ADAPT — Transform data          (agent fills project-specific values)
   ## FIXED — Validate outputs        (assert output shape, column names, ranges)
   

   The ADAPT section should never be the last section.

3. FIXED sections contain zero project-specific values:

   • ✅ {scope_id}, spec["col"], framework constants
   • ❌ hardcoded column names, specific numeric parameters, project nouns

4. ADAPT sections have instructional comments: every ADAPT block must explain what the agent fills, from which source (spec section, prior artefact, etc.), and what format is expected.

5. All Layer A calls are valid: every {package}.* function call in the scaffold must reference a function that exists (or will exist by end of phase). Broken Layer A references are a design defect.

6. Output paths use placeholders: scaffolds write to output/{scope_id}/... not to hardcoded paths.

---

FIXED — Agent Prompt Architecture Rules

Every .agent.md designed in Section D must satisfy:

1. Frontmatter required fields: name, description, tools, model.
2. Worker agents: must include user-invocable: false and disable-model-invocation: true.
3. Orchestrators: must declare agents: [WorkerA, WorkerB] if they invoke workers.
4. argument-hint: required on every user-invocable agent.
5. Handoff self-containment test: any subagent receiving only the handoff prompt (zero session history) must be able to understand what to do.
   • Forbidden in handoff prompts: "the current spec", "what we discussed", "as above"
   • Required: explicit file paths, phase ID, what the worker must produce
6. System prompt structure (in this order):
   1. Role statement (one paragraph)
   2. Session Startup Sequence (numbered steps, #tool:read_file calls explicit)
   3. Authoritative References (table: document → section → use for)
   4. Responsibilities (list or subsections)
   5. Workflows (when X, do Y)
   6. Non-negotiable Rules (numbered list)
7. Worker agent body guard: the first section after startup must check that the invocation prompt contains all required items. If not, halt and list missing items.

---

FIXED — Design Review Workflow

When asked to review an existing design (not produce a new one):

1. Read the artefact under review (SKILL.md, .agent.md, or spec template).
2. Load relevant domain-context SKILL sections to identify:
   • Which dev phase this artefact belongs to
   • Which {package}/ functions it references (Layer A check)
   • Which spec template fields it uses (field continuity check)
3. Check against applicable rules:
   • Function: apply all 7 function design rules
   • SKILL.md: apply all 6 scaffold rules
   • Agent: apply all 7 prompt architecture rules
4. Classify each finding:
   • CONSISTENT — no deviations
   • INCONSISTENT — specific deviation; quote the offending text; cite which rule
   • MISSING — required section/field/rule not present
5. Report: one table row per finding. Summarise with overall CONSISTENT / NEEDS REVISION.
6. Do not fix — report findings to the SCRUM Master for routing to the Implementer.

---

FIXED — Cross-Phase API Continuity

Before designing new function signatures for any phase:

1. Search for existing def declarations in {package}/ to avoid duplication:

   #tool:search/textSearch → "def " in {package}/
   

2. Check for existing modules at the target module path.
3. Ensure no signature change breaks an existing SKILL.md's Layer A call.
   • Search for {package}.module.function in .github/skills/ before changing.
4. Flag any breaking change as BREAKING CHANGE in the design brief Section A, with a list of downstream SKILL.md files that reference the changed function.

---

FIXED — Non-Negotiable Design Constraints

These seven constraints apply to every deliverable designed by the Architect. Any violation is a P0 defect:

1. No unified wrappers for divergent tracks: no UniversalEngine, no UniversalAnalyzer, no cross-track common return types. Each track has its own {package}/ module and SKILL.md.

2. FIXED/ADAPT mandatory in every SKILL.md: FIXED sections must be validatable independently of any project.

3. {package}/ functions are stateless and single-responsibility: no orchestration, no file I/O, no spec reading. Those belong in SKILL.md scaffolds.

4. Spec parameters drive code, not agent memory: all numeric parameters in generated .py scripts must come from load_spec_section() calls (or equivalent), never from hardcoded literals or agent recall.

5. Handoffs are self-contained: every handoff prompt must be a zero-history self-contained brief. Any implicit reference is a design defect.

6. Per-parameter diagnostics (Bayesian tracks only): diagnosis.json must include per_parameter array and worst_parameters field. Loop-back flags must name specific problematic parameters.

7. JSONL manifest, not JSON array: artefacts.jsonl uses one JSON object per line. Never read-modify-write the full file. KB entry IDs must be deduped on append.

---

ADAPT — Framework Document Path and Section Map

Agent instruction: load the domain-context SKILL (e.g., .github/skills/{domain}-builder-context/SKILL.md) at session startup. Read §FIXED — Framework document to populate this section.

• Framework doc path: {framework_doc_path}
• Design principles: §{design_principles_section}
• KB structure: §{kb_section}
• Artefact store / folder structure: §{artefact_section}
• Spec inventory: §{spec_section}
• Agent definitions: §{agents_section}
• Skill contract / FIXED/ADAPT rules: §{skills_section}
• Domain walkthrough (validation scenario): §{walkthrough_section}
• Dev plan (deliverables + validation tests): §{dev_plan_section}
• Deferred items: §{deferred_section}

---

ADAPT — Package Name and Module Map

Agent instruction: read from domain-context SKILL §FIXED — Package.

• Package name: {package_name}
• Package root: {package_root}/
• Top-level modules: {module_list}