Brain-Spoke-Flow

Brain orchestrator + 5 specialist agents, hub-and-spoke architecture, structured development lifecycle — from interview to committed code.

Brain decomposes requests and delegates. Researcher gathers evidence. Planner builds phased plans. Developer implements. Inspector verifies. Curator maintains the workspace. Context flows down only — agents never talk to each other.

Quick Start

git clone https://github.com/awieczork/brain-spoke-flow.git
cd brain-spoke-flow
python setup/bootstrap.py     # creates runtime directories

Open VS Code → Copilot Chat → @brain → describe your task. Brain interviews you, then drives the workflow.

Reset sessions: python setup/reset-sessions.py (--check for dry-run)

Requirements

VS Code + GitHub Copilot Chat
Python 3.10+ (stdlib only — no external modules)

How It Works

Every request flows through a phased lifecycle scaled to complexity:

Scale	Phases	Sessions
Quick fix	Interview → Development	1
Focused task	Interview → Research → Planning → Development → Testing → Review → Curation	1
Feature	Interview → Research → Planning → child Focused tasks	Multi
Project	Interview → Research → child Features	Multi

3 approval gates where you confirm before proceeding: after Interview, after Planning, after Review.

Project Structure

.github/
├── copilot-instructions.md     # Always-on project identity
├── agents/core/                # Brain + 5 subagent definitions
├── contracts/                  # Delegation & return schemas, session spec
├── hooks/                      # 8 deterministic lifecycle hooks (Python)
├── instructions/               # Convention enforcement (glob-scoped)
├── skills/core/                # Creator skills for authoring artifacts
└── prompts/                    # Reusable task templates

docs/                           # Human docs, diagrams, rendered PNGs
setup/                          # bootstrap.py, reset-sessions.py

Runtime data (.github/.sessions/, output/) is gitignored and created by bootstrap.py.

Extending

Add domain-specific artifacts — the framework stays untouched:

Artifact	Location	Scaffolding skill
Domain agents	`agents/domain/{name}.agent.md`	`agent-creator`
Domain skills	`skills/domain/{name}/SKILL.md`	`skill-creator`
Instructions	`instructions/{name}.instructions.md`	`instruction-creator`
Prompts	`prompts/{name}.prompt.md`	—

Docs


ARCHITECTURE.md	Full system specification
docs/workflow-lifecycle.md	Phase-by-phase lifecycle reference
docs/showcase.md	Capabilities overview
.github/hooks/scripts/HOOKS.md	Hook technical reference

Name	skill-creator
Description	Creates SKILL.md files from specifications. Use when user asks to "create a skill", "build a skill", "make a reusable procedure", or "generate skill for [domain]". Produces folder structure, frontmatter, numbered steps, error handling, and validation checks.

skill-creator