ijfw-team

IJFW Team Assembly

Assembles a project-specific operating team. Team Assembly is project-agnostic: it works for software, books, content, design, research, business strategy, education, operations, and mixed projects.

Do not treat every team as a code-generation swarm. Generate the agents plus the operating contracts that let those agents coordinate around artifacts, claims, reviews, and handoffs.

CLI entry point: ijfw team init [--archetype <type>] [--name <team-name>]. ijfw team is the skill/workflow trigger; ijfw team init is the concrete command that writes .ijfw/team/, .ijfw/agents/, and Codex agent files.

How It Works

1. Receive project brief from Discovery stage (or ask for context)
2. Infer one or more project archetypes and artifact types
3. Identify the roles needed for creation, review, integration, and verification
4. Generate portable agent markdown files with proper frontmatter
5. Generate Codex custom-agent TOML when the Codex surface is present
6. Generate the team charter and workflow manifest
7. Present the proposed team and operating model for approval
8. Save approved outputs to .ijfw/agents/, .codex/agents/, and .ijfw/team/ as applicable

Operating Outputs

Team Assembly 2.0 produces three coordinated surfaces:

• .ijfw/agents/*.md -- portable human/platform-readable agent definitions
• .codex/agents/*.toml -- Codex custom agents generated from the same role contracts when Codex is installed or ijfw codex sync-agents is run
• .ijfw/team/charter.json -- team roster, role contracts, phase scope, owned artifacts, reviewed artifacts, conflict rules, handoff requirements, verification responsibilities
• .ijfw/team/workflow.json -- project work manifest: archetypes, artifacts, owners, dependencies, waves, review graph, verification commands or rubrics

Keep .ijfw/agents/*.md lightweight and role-focused. Put machine-readable ownership, dependency, review, and coordination details in the charter and workflow manifest.

Codex TOML agents are platform-native projections, not a separate source of truth. Regenerate them with ijfw codex sync-agents after changing the team charter, and check the local Codex install with ijfw codex doctor.

Project Archetypes

Infer archetypes from the brief, repository signals, existing files, and user corrections. Support mixed projects instead of forcing one label.

Common archetypes:

• software -- modules, APIs, tests, config, docs
• design -- screens, flows, tokens, components, prototypes
• content -- briefs, articles, landing copy, scripts, social posts
• book -- chapters, outline, continuity bible, timeline, notes
• research -- questions, corpus, methods, evidence table, synthesis
• business -- strategy docs, operating plans, models, risk register
• education -- curriculum, lessons, assessments, rubrics
• operations -- SOPs, workflows, runbooks, checklists
• mixed -- any project-specific combination

Domain Templates (starting points -- always customize to the project)

Software Development

• product-lead (sonnet) -- requirements, user stories, acceptance criteria
• architect (opus, high effort) -- system design, security, data model, API design
• senior-dev (sonnet) -- complex implementation, patterns, code review
• dev (sonnet) -- feature implementation, tests, bug fixes
• qa (sonnet) -- test strategy, edge cases, regression testing
• security (opus, high effort) -- threat model, auth, data protection, pen testing
• devops (haiku) -- CI/CD, deployment, infrastructure, monitoring
• docs (haiku) -- documentation, API docs, READMEs, guides

Book / Long-Form Writing

• story-architect (opus, high effort) -- plot structure, pacing, arcs, tension
• world-builder (sonnet) -- settings, environments, atmosphere, sensory detail
• lore-master (haiku) -- continuity bible, rules, history, faction tracking
• prose-stylist (sonnet) -- voice, tone, sentence craft, genre conventions
• continuity-editor (haiku) -- cross-chapter consistency, timeline, character tracking
• beta-reader (sonnet) -- fresh-eyes review, plot holes, reader experience

Content / Marketing

• strategist (opus, high effort) -- campaign strategy, audience, positioning
• copywriter (sonnet) -- headlines, body copy, CTAs, tone of voice
• seo-specialist (haiku) -- keywords, structure, meta, search intent
• editor (sonnet) -- clarity, grammar, consistency, brand voice
• social-media (haiku) -- platform adaptation, hooks, engagement

Business / Strategy

• ceo (opus, high effort) -- vision, strategy, decision-making, priorities
• cto (opus, high effort) -- technical strategy, architecture, build-vs-buy
• analyst (sonnet) -- research, data analysis, market assessment
• operations (sonnet) -- process design, workflows, efficiency
• finance (haiku) -- budgets, projections, cost analysis

Design / Creative

• creative-director (opus, high effort) -- vision, aesthetic direction, brand
• ux-designer (sonnet) -- user flows, wireframes, usability, accessibility
• ui-designer (sonnet) -- visual design, components, responsive layout
• researcher (haiku) -- user research, competitive analysis, testing

Any Other Domain

If the project doesn't match a template above, ask: "What roles would you need on a team to build this well?"

Then generate agents from the user's description. Map each role to a model tier:

• Roles requiring deep reasoning, strategy, or high-stakes decisions -> opus
• Roles doing the primary creation/implementation work -> sonnet
• Roles doing reference checks, lookups, or routine tasks -> haiku

Examples of non-standard teams:

• Game dev: game-designer, level-designer, systems-programmer, qa-tester, narrative-writer
• Scientific research: principal-investigator, literature-reviewer, data-analyst, methodology-reviewer
• Music production: producer, songwriter, mixing-engineer, mastering-engineer
• Event planning: event-director, logistics-coordinator, vendor-manager, creative-designer
• Education: curriculum-designer, subject-expert, assessment-writer, accessibility-reviewer

The templates above are starting points. Every team is customized to the specific project.

Role Contract Guidance

Every role should have a contract in .ijfw/team/charter.json with:

• name, role_type, model, and effort
• phase_scope such as discovery, shape, execute, review, integrate
• owns entries for artifact types and path globs or non-file artifact IDs
• reviews entries with review criteria
• handoff format and required sections
• coordination rules including claim requirements and conflict boundaries
• verification responsibility: commands for code, rubrics for non-code work

Example contract shape:

{
  "name": "ux-researcher",
  "role_type": "research",
  "model": "sonnet",
  "effort": "medium",
  "phase_scope": ["discovery", "shape", "review"],
  "owns": [
    {"artifact_type": "user_flow", "paths": ["design/flows/**"]}
  ],
  "reviews": [
    {"artifact_type": "screen", "criteria": ["usability", "accessibility"]}
  ],
  "handoff": {
    "format": "markdown",
    "required_sections": ["findings", "risks", "recommendations", "changed_artifacts"]
  },
  "coordination": {
    "parallel_safe": true,
    "conflicts_with": ["ui-designer when editing design/tokens/**"],
    "claim_required": true
  }
}

Workflow Manifest Guidance

The workflow manifest describes work in domain terms. It is not just a file list and must not assume code-only verification.

Each artifact entry should include:

• stable id
• domain type
• paths where file-backed, or a non-file artifact reference
• owner
• reviewers
• depends_on
• verification as commands, checks, rubrics, or acceptance criteria

Each wave should include:

• id
• mode: parallel, sequential, or review
• artifact_ids
• dependency rationale when work cannot run in parallel

Example manifest shape:

{
  "project_archetypes": ["software", "design"],
  "artifacts": [
    {
      "id": "design-preview-flow",
      "type": "prototype",
      "paths": [".planning/brainstorm/*.html"],
      "owner": "ui-designer",
      "reviewers": ["ux-designer", "accessibility-reviewer"],
      "depends_on": [],
      "verification": ["ijfw design push .planning/brainstorm/*.html"]
    }
  ],
  "waves": [
    {
      "id": "w1",
      "mode": "parallel",
      "artifact_ids": ["schema-foundation", "design-command-docs"]
    }
  ]
}

Agent File Format

Each generated agent follows this structure:

---
name: <role-name>
model: <haiku|sonnet|opus>
effort: <low|medium|high>
description: <when to use this agent -- 1-2 lines>
allowed-tools: <relevant tools for this role>
---

<Role-specific instructions for this project>

Context from project brief:
<Relevant details from the brief that this agent needs>

Rules:
<Role-specific rules>

Codex Custom Agent Format

When Codex is available, Team Assembly also writes .codex/agents/*.toml from the same role contracts. If .codex/ is absent, unwritable, or intentionally out of scope for the project, keep .ijfw/team/charter.json as canonical, write .ijfw/agents/ markdown role files, and tell the user to run ijfw codex sync-agents later from a writable Codex-enabled checkout. Each Codex TOML file includes:

• name -- stable role identifier
• description -- when to use the agent
• developer_instructions -- project-specific role contract, artifact scope, blackboard discipline, verification, handoff format, and non-revert rules

Optional Codex-only model fields are included only when the role explicitly defines them. Keep the canonical role contract in .ijfw/team/charter.json; use ijfw codex sync-agents to refresh TOML files after team edits.

Codex runtime caveat: some tool-backed sessions expose a generic spawn_agent without named custom-agent invocation. In that case, use the generated TOML as durable role documentation and paste ijfw swarm prompt <task-id> --codex into the built-in worker or explorer agent. The prompt is designed to carry the full artifact scope and blackboard contract even without named custom-agent routing.

Team Presentation

After generating, present the team and operating outputs as:

Project team ready:

  architect (opus)  -- system design, security model, API surface
  senior-dev (sonnet) -- auth flow, payment integration, complex features
  dev (sonnet) -- CRUD endpoints, tests, UI components
  qa (sonnet) -- test strategy, edge cases, regression suite
  security (opus) -- threat model, auth audit, data protection

Agents saved to .ijfw/agents/
Codex agents saved to .codex/agents/ when Codex agent sync is available; otherwise .ijfw/team/charter.json remains canonical
Charter saved to .ijfw/team/charter.json
Workflow saved to .ijfw/team/workflow.json
Codex health check: ijfw codex doctor
Adjust with: "swap qa for a dedicated performance engineer"

Positive framing. Team is "ready" not "generated." Feels like hiring, not configuring.

Execution Model

During workflow Execute stage, tasks are dispatched through the workflow manifest and charter:

• Match each task to an owner, artifact IDs, allowed paths or artifact scope, completion criteria, and verification method
• Require blackboard claims before an agent edits or owns an artifact during parallel work
• Use parallel waves only when artifact claims and dependencies do not conflict
• Use sequential waves where dependencies, claims, or integration order require it
• Generate review tasks from the review graph, not as informal suggestions
• Record findings, decisions, blockers, claims, and handoffs in .ijfw/blackboard/
• Treat review findings as integration gates when severity or criteria require it

Review examples:

• security reviews auth and data-handling artifacts
• editor reviews brand and clarity for content artifacts
• continuity-editor reviews timeline and character artifacts
• methodology-reviewer audits evidence and research methods
• operations reviews SOP failure modes and dry-run readiness

Blackboard Coordination

Team Assembly should prepare agents to coordinate through the project blackboard when execution begins:

• .ijfw/blackboard/tasks.json tracks task graph and statuses
• .ijfw/blackboard/claims.json tracks active artifact ownership
• .ijfw/blackboard/findings.jsonl records review notes and issues
• .ijfw/blackboard/decisions.jsonl records runtime decisions
• .ijfw/blackboard/blockers.jsonl records blocked work
• .ijfw/blackboard/handoff.md summarizes active swarm state

Claims are artifact-aware. A claim can be a file glob, chapter, design token set, research corpus, strategy model, lesson plan, or any project-specific artifact. Agents must release or hand off claims when their task completes.

Worktree Policy

Worktrees are optional and only for code-heavy projects or code-heavy portions of mixed projects.

Use git worktrees when:

• multiple software agents need to edit overlapping repository areas in parallel
• the user explicitly requests swarm execution with isolated code edits
• task verification can run independently before integration

Do not require worktrees for:

• writing, editing, research, strategy, operations, education, or design-only work
• mixed projects where only non-code artifacts are being changed
• dirty worktrees with unrelated user changes unless the user approves the isolation plan

For non-code and mixed non-code work, use blackboard claims, artifact-scoped output paths, and staged review gates instead.

Custom Agent Requests

User can always:

• "Add a performance engineer to the team"
• "I need a lore master who specialises in cyberpunk tech"
• "Swap the junior dev for a frontend specialist"
• "Remove the SEO specialist, I don't need that"

Modifications update .ijfw/agents/ immediately. AGENTS.md remains the canonical cross-platform instruction surface; after team changes, update only the IJFW-AGENTS managed region with the current role names, owned artifacts, and agent file paths. Preserve all content outside IJFW markers. If the block-aware AGENTS merger is available, use it; otherwise record a checkpoint and state exactly which AGENTS region still needs mirroring.

Portability

Agents in .ijfw/agents/ work with any platform that reads agent markdown. If .forge/ directory exists, IJFW also reads agents from there. .ijfw/ and .forge/ are treated as compatible project directories.