Workflow Scaffold (navigation + concierge)
Workflow Scaffold (navigation + concierge)
Section titled “Workflow Scaffold (navigation + concierge)”Purpose
Section titled “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)
Section titled “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
Section titled “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
Section titled “Navigation Map”Tier 1 — 01-kernel/ (universal)
Section titled “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)
Section titled “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)
Section titled “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
Section titled “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)
Section titled “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)
Section titled “Common Questions (answer directly)”“Where do I start?”
Section titled ““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?”
Section titled “”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?”
Section titled “”How do I add domain expertise?””skill-writer agent (ask first).
”What’s the difference between skills and agents?”
Section titled “”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?”
Section titled “”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?”
Section titled “”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?”
Section titled “”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
Section titled “Workflow Patterns”Pattern 1: Start a new project from the scaffold
Section titled “Pattern 1: Start a new project from the scaffold”- Decide: deterministic (use
scripts/setup.sh) or interview (useseacow-scaffolderagent). - If interview → ask first, then spawn agent.
- Scaffolder creates structure based on user’s context.
Pattern 2: Add domain expertise
Section titled “Pattern 2: Add domain expertise”- Identify the domain/task type.
- Ask: “Want me to spawn
skill-writerfor [domain]?” - If yes → agent creates skill in correct format.
- Verify the description covers the right activation contexts.
Pattern 3: Create a new specialist agent
Section titled “Pattern 3: Create a new specialist agent”- Identify the repeatable work.
- Ask: “Want me to spawn
agent-writerfor this?” - If yes → agent creates file with appropriate tools and skills.
Pattern 4: Understand your organization
Section titled “Pattern 4: Understand your organization”- Load
seacow-conventionsskill. - Ask SEACOW questions about the situation.
- Design YOUR structure based on YOUR answers — don’t copy, think.
Pattern 5: Scaffold maintenance after changes
Section titled “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-updaterorworkflow-expertto check docs?”
Maintenance Reminders
Section titled “Maintenance Reminders”After user adds an agent:
- “Remember to add it to
AGENTS.mdandCLAUDE.md’s Available Agents section.” - Or: “Want me to spawn
workflow-expertto update docs?”
After user adds a skill:
- “Skills should be at
01-kernel/skills/<name>/SKILL.mdwith YAML frontmatter (name,description,stratum). Remember to update CLAUDE.md’s skills list.”
After structural changes:
- “Want me to spawn
claude-md-updaterto 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
Section titled “File Conventions”Frontmatter
Section titled “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
Section titled “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
Section titled “_index.md / section README”Each section directory can have an index.md for sidebar navigation and orientation.
- 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, matches00-inbox/existing convention)
Effective Agent Usage
Section titled “Effective Agent Usage”When to offload to an agent
Section titled “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
Section titled “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
Section titled “The distillation pipeline”Main → Agent A (explores /docs/) → returns summary → Agent B (explores /src/) → returns summary → Main synthesizes with clean contextEach level distills. Parents receive only summaries.
Deep dive on delegation decisions: delegation-advisor skill (also works with ask-first pattern).
Troubleshooting
Section titled “Troubleshooting””Agent X can’t be found”
Section titled “”Agent X can’t be found””- Check path:
01-kernel/agents/<name>.md(or the.claude/agents/symlink) - Verify YAML frontmatter present
- Ensure
descriptionfield exists (Claude uses this for auto-invocation)
“Skill not loading when I expect it”
Section titled ““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
descriptionfor semantic matching (NOT keyword matching) - Review skill’s description — does it cover the contexts you’re activating in?
”Structure feels wrong for my context”
Section titled “”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”
Section titled “”Too much to read””Start with:
README.md(5 min)01-kernel/PHILOSOPHY.md(10 min)- Try
seacow-scaffolderon a small project
Learn by doing, not reading everything first.
Key Distinction
Section titled “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
Section titled “See Also”01-kernel/PHILOSOPHY.md— invariants of the system01-kernel/principles/— 10 principle pages (philosophy)01-kernel/patterns/— named patterns (SEACOW lens, meta-agent pattern, etc.)01-kernel/ARCHITECTURE.md— tool composability detailsseacow-conventionsskill — SEACOW framework deep diveskill-patterns/agent-patternsskills — designing new componentsdelegation-advisorskill — when delegation is the right call
History
Section titled “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.