| name | workflow-scaffold |
| description | Concierge for navigating, using, and maintaining this workflow scaffold. Use when users ask about scaffold structure, where things go, conventions, how to get started, how to do scaffold-level work, or when scaffold actions may need delegation to agents. Answers directly when possible; ASKS before spawning agents. |
| stratum | 2 |
| branches | ["agentic"] |
Workflow Scaffold (navigation + concierge)
Purpose
Expertise in understanding, navigating, and maintaining this workflow scaffold. This skill combines two closely-related concerns that previously lived in separate skills:
- Navigation ā where things live, what each part does, how pieces connect
- Concierge / delegation ā recognizing when a task needs an agent and asking before spawning one
Load this skill when users ask about the scaffold itself (its structure, conventions, patterns) OR when they're about to do work that may benefit from agent delegation.
I am a skill (lightweight, loaded into context). When I recognize work that needs an agent (heavyweight, fresh context), I ASK before delegating rather than auto-invoking.
Ask-First Pattern (how I work)
When I detect a task that could benefit from an agent:
- RECOGNIZE the task type
- ASK via
AskUserQuestion: "Would you like me to spawn [agent]?"
- RESPECT the user's choice ā direct handling is always valid
- DELEGATE only with approval, passing relevant context
This prevents context waste from unnecessary agent spawns while keeping the option available.
What This Scaffold Is
A scaffolding + progressive agent memory system organized in three tiers:
| Zone | Tier | Purpose |
|---|
01-kernel/ | Universal | Philosophy, patterns, meta-agents, templates, scripts ā forkable by anyone |
02-stack/ | Opinionated | Tool installs, configs, helpers ā forkable for similar setups |
03-work/ | Personal | Project patterns, agent memory, rebuild guide ā mostly personal |
00-meta/ | Tooling | Kernel-dev scripts, audits, test-workspace |
Deep dive on the structure and philosophy: 01-kernel/PHILOSOPHY.md + 01-kernel/principles/.
Navigation Map
Tier 1 ā 01-kernel/ (universal)
| Path | Purpose |
|---|
PHILOSOPHY.md | Invariant claims about knowledge work |
principles/ | Named philosophical principles (stratum 1) |
patterns/ | Named patterns ā SEACOW lens, meta-agent pattern, hook pattern, etc. (stratum 2) |
templates/ | Parametric templates ā AGENTS.md.tmpl, skeleton directory, skill/agent tmpls (stratum 3) |
scripts/ | Deterministic scripts ā install.sh, hooks, seacow-scaffolder (stratum 4) |
skills/ | Meta-skills for agentic work (this file included) |
agents/ | Meta-agents ā scaffolder, writers, improvers |
commands/ | Slash commands ā /task-plan, /improve, /validate, etc. |
Tier 2 ā 02-stack/ (opinionated toolkit)
| Path | Purpose |
|---|
01-ai-coding/ | Claude Code + OpenCode install & config |
02-terminal/ | Zellij, WezTerm, Alacritty setup |
03-cross-device/ | Tailscale SSH, Termux |
04-knowledge-mgmt/ | Obsidian + CLI |
05-homelab/ | General homelab patterns |
06-dev-infra/ | Docker, Git, utilities |
07-editor-ext/ | VS Code extensions |
profiles/ | Bashrc helpers + keybindings (stack-specific) |
patterns/ | Stack-level patterns (cross-device, parallel-agents-worktrees, obsidian-workflow) |
install/ | Install scripts for the stack |
decisions/ | Decision matrices (Claude Code vs OpenCode, etc.) |
Tier 3 ā 03-work/ (personal workflow)
| Path | Purpose |
|---|
project-types/ | How the user builds each type (Astro+Starlight docs, etc.) |
memory/ | Agent-consumable preferences, tool picks, project references |
rebuild/ | The user's specific rebuild-my-machine walkthrough |
homelab/ | User's specific home lab (TrueNAS, MCP endpoints, Tailscale) |
references/ | Links to external projects as living examples |
Root Level
| File | Purpose |
|---|
README.md | Vision-first quick start |
CLAUDE.md | Conventions for THIS repo |
AGENTS.md | Portable agent definitions (stratum 5 ā describes THIS repo) |
ROADMAP.md | This repo's roadmap |
Delegation Triggers (ASK before spawning)
| User is asking / trying to... | Recommend spawning... |
|---|
| "How does X work in this scaffold?" deep investigation | workflow-expert agent |
| "Where should I put Y?" requires file-level analysis | workflow-expert agent |
| "What's the convention for Z?" | answer directly if simple; else workflow-expert |
| "Set up a new project/vault/structure at [path]" | seacow-scaffolder agent |
| "Create a skill for [domain]" | skill-writer agent |
| "Create an agent that [does X]" | agent-writer agent |
| "Check/update CLAUDE.md after my changes" | claude-md-updater agent |
| "Audit my existing project's structure" | workspace-advisor agent |
| Any "How does X work in [large codebase]?" | built-in Explore (Task tool) |
| Pre-implementation design for multi-file changes | built-in Plan (Task tool) |
| Complex task the user expects will need multiple steps | general-purpose (Task tool) |
When recommending, use AskUserQuestion with wording like:
"This looks like it needs a [agent] agent ā it'll give us [benefit]. Want me to spawn one?"
Common Questions (answer directly)
"Where do I start?"
README.md for the quick overview, then 01-kernel/PHILOSOPHY.md for the why.
"How do I create a new project?"
seacow-scaffolder agent (ask first). Or the deterministic scripts/setup.sh if the template is obvious.
"How do I add domain expertise?"
skill-writer agent (ask first).
"What's the difference between skills and agents?"
- Skill = passive expertise (loaded into same context, no tool use)
- Agent = active executor (fresh context window, can use tools, returns summary)
Deep dive: 01-kernel/principles/03-skills-vs-agents.md.
"What is SEACOW?"
An analytical lens (not a folder structure): S-ystem, E-ntity, A-ctivities (Capture/Output/Work), r-elation. It's a set of questions for thinking about organization. Load seacow-conventions skill for the full framework.
"Can I use this with tools other than Claude Code?"
Yes ā AGENTS.md is portable to 20+ AI tools. Key constraint differences:
- Claude Code: agents cannot spawn other agents (sequential composition only)
- OpenCode: agents CAN spawn child agents (recursive composition)
Deep dive: 02-stack/decisions/tool-comparison.md or 01-kernel/ARCHITECTURE.md.
"What's the stratum: field in frontmatter?"
A classification (1ā5) indicating how portable a file is:
- 1 philosophy ā always true; anyone can adopt
- 2 pattern ā same shape, different content; named patterns
- 3 parametric ā fill-in-the-blank templates
- 4 deterministic ā drop-in scripts, fixed content
- 5 instance ā specific to this user; not a template
Deep dive: 01-kernel/principles/07-five-strata.md.
Workflow Patterns
Pattern 1: Start a new project from the scaffold
- Decide: deterministic (use
scripts/setup.sh) or interview (use seacow-scaffolder agent).
- If interview ā ask first, then spawn agent.
- Scaffolder creates structure based on user's context.
Pattern 2: Add domain expertise
- Identify the domain/task type.
- Ask: "Want me to spawn
skill-writer for [domain]?"
- If yes ā agent creates skill in correct format.
- Verify the description covers the right activation contexts.
Pattern 3: Create a new specialist agent
- Identify the repeatable work.
- Ask: "Want me to spawn
agent-writer for this?"
- If yes ā agent creates file with appropriate tools and skills.
Pattern 4: Understand your organization
- Load
seacow-conventions skill.
- Ask SEACOW questions about the situation.
- Design YOUR structure based on YOUR answers ā don't copy, think.
Pattern 5: Scaffold maintenance after changes
- User adds/modifies a skill/agent.
- Remind: "Remember to update
CLAUDE.md / AGENTS.md."
- Offer: "Want me to spawn
claude-md-updater or workflow-expert to check docs?"
Maintenance Reminders
After user adds an agent:
- "Remember to add it to
AGENTS.md and CLAUDE.md's Available Agents section."
- Or: "Want me to spawn
workflow-expert to update docs?"
After user adds a skill:
- "Skills should be at
01-kernel/skills/<name>/SKILL.md with YAML frontmatter (name, description, stratum). Remember to update CLAUDE.md's skills list."
After structural changes:
- "Want me to spawn
claude-md-updater to check if docs need updating?"
After a research insight worth keeping:
- "Is this methodology (fits in a tier) or knowledge work (exits to external vault)? If methodology, which tier ā kernel (universal), stack (your toolkit), or work (your specific patterns)?"
File Conventions
Frontmatter
Every markdown file in a tier should have:
---
title: <page title>
description: <one-line purpose>
stratum: <1-5>
status: <research | planning | stable | parked>
tags: []
date: YYYY-MM-DD
---
Wikilinks
Obsidian-style [[path/to/file]] works via remark-wiki-link. Prefer wikilinks for cross-references; regular markdown links for external URLs.
_index.md / section README
Each section directory can have an index.md for sidebar navigation and orientation.
Names
- Skills:
01-kernel/skills/<name>/SKILL.md
- Agents:
01-kernel/agents/<name>.md
- Commands:
01-kernel/commands/<name>.md
- Principles:
01-kernel/principles/NN-<name>.md (numeric prefix for sidebar order)
- Tier zone folders:
NN-<name>/ (dash separator, matches 00-inbox/ existing convention)
Effective Agent Usage
When to offload to an agent
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā SHOULD I OFFLOAD THIS TO A SUBAGENT? ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā¤
ā Will this require reading more than 3-5 files? ā
ā āāā YES ā Spawn subagent (Explore/Plan/specialist) ā
ā āāā NO ā Do it directly ā
ā ā
ā Am I asking "how does X work in this codebase?" ā
ā āāā YES ā Spawn Explore agent ā
ā āāā NO ā Continue ā
ā ā
ā Is this a multi-step implementation with architectural choice? ā
ā āāā YES ā Spawn Plan agent first, review, then implement ā
ā āāā NO ā Do it directly ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Context budget awareness
Agents spawn with fresh context. When the main context is approaching ~40% used on exploration, offloading to an agent prevents further bloat. The agent returns a compressed summary; main context stays clean for synthesis.
The distillation pipeline
Main ā Agent A (explores /docs/) ā returns summary
ā Agent B (explores /src/) ā returns summary
ā Main synthesizes with clean context
Each level distills. Parents receive only summaries.
Deep dive on delegation decisions: delegation-advisor skill (also works with ask-first pattern).
Troubleshooting
"Agent X can't be found"
- Check path:
01-kernel/agents/<name>.md (or the .claude/agents/ symlink)
- Verify YAML frontmatter present
- Ensure
description field exists (Claude uses this for auto-invocation)
"Skill not loading when I expect it"
- Skills need subdirectory structure:
01-kernel/skills/<name>/SKILL.md
- SKILL.md must have YAML frontmatter (
name, description, stratum)
- Claude uses
description for semantic matching (NOT keyword matching)
- Review skill's description ā does it cover the contexts you're activating in?
"Structure feels wrong for my context"
- Examples are not prescriptions
- Use SEACOW thinking to design YOUR structure
- The tier structure (kernel/stack/work) is THIS repo's decomposition ā your project may need a different decomposition
"Too much to read"
Start with:
README.md (5 min)
01-kernel/PHILOSOPHY.md (10 min)
- Try
seacow-scaffolder on a small project
Learn by doing, not reading everything first.
Key Distinction
| Component | Role |
|---|
| workflow-scaffold (this skill) | Concierge ā answers directly or ASKS to delegate |
| workflow-expert (agent) | Specialist ā deep investigation of scaffold content |
| seacow-scaffolder (agent) | Builder ā creates NEW structures elsewhere |
| delegation-advisor (skill) | Focused companion ā when the delegation decision itself is the question |
This skill is the lightweight trigger. The agents do the heavy lifting.
See Also
01-kernel/PHILOSOPHY.md ā invariants of the system
01-kernel/principles/ ā 10 principle pages (philosophy)
01-kernel/patterns/ ā named patterns (SEACOW lens, meta-agent pattern, etc.)
01-kernel/ARCHITECTURE.md ā tool composability details
seacow-conventions skill ā SEACOW framework deep dive
skill-patterns / agent-patterns skills ā designing new components
delegation-advisor skill ā when delegation is the right call
History
Merged from workflow-guide + workflow-meta during Phase 1 restructure (2026-04-17). The two previous skills had near-identical purposes (navigation + meta-question handling + ask-first delegation); combining into one resolved the redundancy.