Faion umbrella
Single entry point for the entire faion knowledge + workflow stack. Auto-invokes on a wide range of triggers — see description above for the full routing surface.
Routing
When invoked, decide what the user needs and read the right entry point:
| Signal |
Read |
| Methodology question |
L1: knowledge/domains.xml → pick ≤3 domains → L2: knowledge/<domain>/INDEX.xml → leaf: knowledge/<tier>/<group>/<name>/AGENTS.md |
| "How to do X" — concrete task with steps |
L1: playbooks/taxonomy.xml (11 goal categories) → L2: playbooks/by-goal/<goal>/INDEX.xml → leaf: playbooks/<goal>/<slug>/AGENTS.md + content/01-playbook.xml |
| Build / run it, not read about it — "build a research-first product", "run this SDD feature", "write and translate an article", "audit and fix this tree" |
L2: recipes/INDEX.xml → leaf: recipes/<name>/<name>.card.md. Supporting: fragments/INDEX.xml (the role prompts a recipe composes) · tools/INDEX.xml (scripts to run instead of writing one) |
| Workflow needed (brainstorm / SDD batch / improver / media pipeline / agent pool) |
workflows/AGENTS.md to pick + load |
A task that names a deliverable and a pipeline to produce it routes to recipes, not into the methodology corpus: a methodology tells you what good looks like, a recipe is the thing that runs.
Methodology layout (v3, post-F-066):
knowledge/<tier>/<group>/<slug>/
├── AGENTS.md # envelope: frontmatter + 11 body sections incl. ## Decision tree
└── content/
├── 01-core-rules.xml # ≥5 testable rules + rationale + source
├── 02-output-contract.xml # JSON Schema + valid/invalid examples
├── 03-failure-modes.xml # ≥3 antipatterns (symptom/root-cause/fix)
├── 04-procedure.xml # step-by-step if complexity ≥ medium
├── 05-examples.xml # worked example if produces ∈ {spec, report}
└── 06-decision-tree.xml # MANDATORY: root-question + branches → conclusion(ref=rule-id)
├── templates/ # real working skeletons declared in AGENTS.md
└── scripts/validate-<slug>.py # output-contract validator if schema present
Knowledge retrieval pipeline (default behaviour)
When the user has a domain question and no specific workflow trigger fired, spawn a read-only Agent SDK subagent that:
- reads the current session transcript (user + assistant text only — no tool calls, no system reminders)
- searches
knowledge/ (cwd-scoped) for relevant methodology files
- either:
- calls
submit_selection (validates word budget; retries if over) → returns <faion_knowledge> bundle, OR
- calls
request_clarification → returns <faion_clarification> with questions for the user
The output is XML.
- If
<faion_knowledge> — read each <document> as relevant context. Inlined <faion-methodology slug="..."> blocks are pre-parsed methodology bodies (metadata stripped); treat them as the primary content.
- If
<faion_clarification> — follow the <instruction_to_main_agent> block: ask the user via AskUserQuestion using the embedded questions, append their answers to the conversation, then re-invoke /faion.
python3 ~/workspace/projects/faion-net/faion-network/skills/faion/scripts/retrieve.py "${CLAUDE_SESSION_ID:-}"
Workflows (auto-routed)
| Trigger |
Workflow folder |
| "brainstorm", "10 ideas", "audit X", "diverge-converge", "give me options" — and brainstorm is new in this session |
workflows/brainstorm/ (consent gate runs first if not user-initiated) |
"виконай feature-NNN", batch of features in .aidocs/<project>/todo/, multi-feature SDD delivery |
workflows/sdd-batch-orchestrator/ |
| "що зробили в сесії", "audit my server", "find issues", "improve system", "what did we learn" |
workflows/improver/ |
| "новий медіа-пайплайн", "TG channel + сайт", "AI news pipeline", "media outlet" |
workflows/media-ops/ |
| "пул фонових агентів", "queue of N batches", "background pool dispatch" |
workflows/poll-agents/ |
To use a workflow: read its AGENTS.md (≤80 lines), then act per the phases described.
Recipes, fragments and tools
The composable layer: pipelines an agent runs, not prose it reads. Three L2 indexes, generated from meta.json by scripts/regen-fragment-index.py.
| Index |
Holds |
Read the leaf as |
recipes/INDEX.xml |
4 workflow recipes — sdd-feature (free, 6 stages), research-first-build (free, 13), article-pipeline (free, 6), audit-and-fix (free, 4) |
<name>.card.md — the card is the contract and is enough to invoke from; recipe.json is the compiler's input, never the agent's |
fragments/INDEX.xml |
6 packs of role prompts a recipe composes, addressed corpus:<name> |
the fragment body, or faion frag get corpus:<name> |
tools/INDEX.xml |
3 packs of dependency-free scripts |
<name>.card.md — read the card, never the script, and never re-implement a tool that already has one |
The whole layer ships at tier free — the pipeline is the mechanism that makes output correct, and what a tier buys is the content a pipeline consumes, not the pipeline. A fragment's tier is still always ≤ the tier of every recipe that composes it, so picking a recipe you can read never yields a stage you cannot. Compile a recipe with faion workflow build <recipe.json> --var ….
Playbooks
Beyond knowledge methodologies, the faion umbrella also hosts 455 playbooks at playbooks/<goal>/<slug>/ — AGENTS.md (stages, each with a decision gate) plus content/01-playbook.xml. A playbook is a standalone how-to for one task; the folder it sits in is the goal character of that task, not who runs it and not what it costs.
Tier is carried per playbook in its own meta.json and enforced through skills/tier-manifest.json, never by directory. Each playbook cites ≥1 methodology from knowledge/<domain>/<slug>/, at a tier ≤ its own.
Route L1 playbooks/taxonomy.xml → L2 playbooks/by-goal/<goal>/INDEX.xml → leaf. by-goal/ holds the 11 generated indexes and no content; regenerate them with python3 scripts/regen-playbook-index.py.
1---2name: faion3description: "Faion umbrella for solopreneur dev work. AUTO-INVOKE on ANY of: (a) domain methodology lookup across 20 canonical knowledge domains (~2628 methodologies — dev, backend, frontend, infra, ai-core, ai-agents, ml-engineering, sdlc-ai, pm, product, ba, marketing, research, ux, sdd, architecture, security, comms, hr, claude-code); (b) playbook how-to (455 guides at playbooks/<goal>/<slug>/) organised by 11 goal-character categories; (c) multi-agent brainstorming / diverge-converge / 'give me 10 ideas' (MUST ASK USER FIRST if brainstorm wasn't explicitly requested); (d) single-feature or batch SDD execution (study → clarify → plan → wave-execute → verify → review → fix → close); (e) session-based improvement / system audit / 'що ми зробили' / 'find issues'; (f) AI media pipeline construction (TG channel + site + automation); (g) self-replenishing background agent pool for long task queues; (h) a task-shaped need that wants a *pipeline* rather than a document — 'build a research-first product', 'run an SDD feature en"4---56# Faion umbrella78Single entry point for the entire faion knowledge + workflow stack. Auto-invokes on a wide range of triggers — see `description` above for the full routing surface.910## Routing1112When invoked, decide what the user needs and read the right entry point:1314| Signal | Read |15|--------|------|16| Methodology question | L1: `knowledge/domains.xml` → pick ≤3 domains → L2: `knowledge/<domain>/INDEX.xml` → leaf: `knowledge/<tier>/<group>/<name>/AGENTS.md` |17| "How to do X" — concrete task with steps | L1: `playbooks/taxonomy.xml` (11 goal categories) → L2: `playbooks/by-goal/<goal>/INDEX.xml` → leaf: `playbooks/<goal>/<slug>/AGENTS.md` + `content/01-playbook.xml` |18| **Build / run it, not read about it** — "build a research-first product", "run this SDD feature", "write and translate an article", "audit and fix this tree" | L2: `recipes/INDEX.xml` → leaf: `recipes/<name>/<name>.card.md`. Supporting: `fragments/INDEX.xml` (the role prompts a recipe composes) · `tools/INDEX.xml` (scripts to run instead of writing one) |19| Workflow needed (brainstorm / SDD batch / improver / media pipeline / agent pool) | `workflows/AGENTS.md` to pick + load |2021A task that names a **deliverable and a pipeline to produce it** routes to recipes, not into the methodology corpus: a methodology tells you what good looks like, a recipe is the thing that runs.2223**Methodology layout (v3, post-F-066):**2425```26knowledge/<tier>/<group>/<slug>/27├── AGENTS.md # envelope: frontmatter + 11 body sections incl. ## Decision tree28└── content/29 ├── 01-core-rules.xml # ≥5 testable rules + rationale + source30 ├── 02-output-contract.xml # JSON Schema + valid/invalid examples31 ├── 03-failure-modes.xml # ≥3 antipatterns (symptom/root-cause/fix)32 ├── 04-procedure.xml # step-by-step if complexity ≥ medium33 ├── 05-examples.xml # worked example if produces ∈ {spec, report}34 └── 06-decision-tree.xml # MANDATORY: root-question + branches → conclusion(ref=rule-id)35├── templates/ # real working skeletons declared in AGENTS.md36└── scripts/validate-<slug>.py # output-contract validator if schema present37```3839## Knowledge retrieval pipeline (default behaviour)4041When the user has a domain question and no specific workflow trigger fired, spawn a read-only Agent SDK subagent that:42431. reads the current session transcript (user + assistant text only — no tool calls, no system reminders)442. searches `knowledge/` (cwd-scoped) for relevant methodology files453. either:46 - calls `submit_selection` (validates word budget; retries if over) → returns `<faion_knowledge>` bundle, OR47 - calls `request_clarification` → returns `<faion_clarification>` with questions for the user4849The output is XML.50- If `<faion_knowledge>` — read each `<document>` as relevant context. Inlined `<faion-methodology slug="...">` blocks are pre-parsed methodology bodies (metadata stripped); treat them as the primary content.51- If `<faion_clarification>` — follow the `<instruction_to_main_agent>` block: ask the user via AskUserQuestion using the embedded questions, append their answers to the conversation, then re-invoke `/faion`.5253```!54python3 ~/workspace/projects/faion-net/faion-network/skills/faion/scripts/retrieve.py "${CLAUDE_SESSION_ID:-}"55```5657## Workflows (auto-routed)5859| Trigger | Workflow folder |60|---------|-----------------|61| "brainstorm", "10 ideas", "audit X", "diverge-converge", "give me options" — and brainstorm is new in this session | `workflows/brainstorm/` (consent gate runs first if not user-initiated) |62| "виконай feature-NNN", batch of features in `.aidocs/<project>/todo/`, multi-feature SDD delivery | `workflows/sdd-batch-orchestrator/` |63| "що зробили в сесії", "audit my server", "find issues", "improve system", "what did we learn" | `workflows/improver/` |64| "новий медіа-пайплайн", "TG channel + сайт", "AI news pipeline", "media outlet" | `workflows/media-ops/` |65| "пул фонових агентів", "queue of N batches", "background pool dispatch" | `workflows/poll-agents/` |6667To use a workflow: read its `AGENTS.md` (≤80 lines), then act per the phases described.6869## Recipes, fragments and tools7071The composable layer: pipelines an agent runs, not prose it reads. Three L2 indexes, generated from `meta.json` by `scripts/regen-fragment-index.py`.7273| Index | Holds | Read the leaf as |74|-------|-------|------------------|75| `recipes/INDEX.xml` | 4 workflow recipes — `sdd-feature` (free, 6 stages), `research-first-build` (free, 13), `article-pipeline` (free, 6), `audit-and-fix` (free, 4) | `<name>.card.md` — the card is the contract and is enough to invoke from; `recipe.json` is the compiler's input, never the agent's |76| `fragments/INDEX.xml` | 6 packs of role prompts a recipe composes, addressed `corpus:<name>` | the fragment body, or `faion frag get corpus:<name>` |77| `tools/INDEX.xml` | 3 packs of dependency-free scripts | `<name>.card.md` — read the card, never the script, and never re-implement a tool that already has one |7879The whole layer ships at tier **free** — the pipeline is the mechanism that makes output correct, and what a tier buys is the content a pipeline consumes, not the pipeline. A fragment's tier is still always ≤ the tier of every recipe that composes it, so picking a recipe you can read never yields a stage you cannot. Compile a recipe with `faion workflow build <recipe.json> --var …`.8081## Playbooks8283Beyond knowledge methodologies, the faion umbrella also hosts **455 playbooks** at `playbooks/<goal>/<slug>/` — `AGENTS.md` (stages, each with a decision gate) plus `content/01-playbook.xml`. A playbook is a standalone how-to for one task; the folder it sits in is the **goal character** of that task, not who runs it and not what it costs.8485Tier is carried per playbook in its own `meta.json` and enforced through `skills/tier-manifest.json`, never by directory. Each playbook cites ≥1 methodology from `knowledge/<domain>/<slug>/`, at a tier ≤ its own.8687Route L1 `playbooks/taxonomy.xml` → L2 `playbooks/by-goal/<goal>/INDEX.xml` → leaf. `by-goal/` holds the 11 generated indexes and no content; regenerate them with `python3 scripts/regen-playbook-index.py`.