Moai Workflow Design Context

moai-workflow-design-context

Loads human-authored design brief documents from .moai/design/ and injects a token-capped consolidated context block into the orchestrator prompt before expert-frontend or moai-domain-brand-design is invoked.

This skill is called automatically during Phase B2.5 of the /moai design workflow when design_docs.auto_load_on_design_command is true, and can also be invoked standalone with an explicit dir argument.

Quick Reference

Priority order (REQ-2, AC-4): spec > system > research > pencil-plan

Bare-token to filename mapping:

• spec → .moai/design/spec.md
• system → .moai/design/system.md
• research → .moai/design/research.md
• pencil-plan → .moai/design/pencil-plan.md

Token budget default: 20000 (from design.yaml design_docs.token_budget)

Token estimation algorithm (REQ-5): estimated_tokens = ceiling(char_count / 4) * 1.10

Truncation order when over budget (REVERSE priority): drop pencil-plan first, then research, then system; always preserve spec.

Implementation Guide

Step 1: Resolve Configuration

Read design_docs from .moai/config/sections/design.yaml. If design_docs key is absent, use compiled-in defaults and log:

design_docs not configured — using defaults

Defaults:

• dir: .moai/design
• auto_load_on_design_command: true
• token_budget: 20000
• priority: [spec, system, research, pencil-plan]

If invoked standalone with an explicit dir argument, override dir with the provided value. All Read tool calls must target paths under <dir>/, not the default .moai/design/.

Step 2: Check Directory Existence

Use Glob to check whether <dir>/ exists. If the directory does not exist, return gracefully with an empty context block and log:

design docs not initialized — run /moai init or SPEC-DESIGN-DOCS-001 to create

Return:

## Design Context (from .moai/design/)

(header only, no content lines)

Step 3: Auto-Load Gate (REQ-1, REQ-9)

When invoked from Phase B2.5 (not standalone), check design_docs.auto_load_on_design_command. If false, skip and return an empty context block. Do not auto-invoke; respond only to explicit standalone calls with dir.

Step 4: Parallel File Discovery and Read (REQ-11, AC-13)

Issue all Read tool calls for candidate files as a single batched parallel tool-call set in the same orchestration turn. The candidates are the bare tokens from the priority array, mapped to <dir>/<token>.md.

Example parallel Read calls (four files, one turn):

• Read <dir>/spec.md
• Read <dir>/system.md
• Read <dir>/research.md
• Read <dir>/pencil-plan.md

If a file does not exist, treat as not present (not an error). If a file cannot be read due to a permission error or corruption, add the token name to the warnings array and continue with remaining files (partial success semantics, REQ-14, AC-15).

Step 5: Filter TBD Files (REQ-3, AC-5)

For each successfully read file, check whether the content contains exclusively _TBD_ markers (i.e., no user-authored sections — all non-empty lines are _TBD_ or YAML/Markdown structural lines produced by scaffolding with no user content).

A file is considered _TBD_-only when every meaningful content line matches:

• Blank lines or lines containing only _TBD_
• Markdown headings with no body text beyond scaffold headings
• The scaffold comment pattern (lines starting with <!-- or >)

If _TBD_-only, skip the file and log:

skip: <token> — _TBD_ only

Step 6: Token Budget Enforcement (REQ-4, REQ-5, AC-9)

After filtering, compute the estimated token count for each remaining file:

estimated_tokens(file) = ceiling(len(content) / 4) * 1.10

Include files in priority order (spec first) until the cumulative estimated_tokens would exceed token_budget.

When adding the next file would exceed the budget:

1. Drop the lowest-priority candidate first (REVERSE priority: pencil-plan before research before system; never drop spec).
2. Retry with remaining files.
3. If a single file alone exceeds the remaining budget after all higher-priority files are included, truncate that file at the nearest ## or ### section boundary before the budget is exceeded, then append a trailing marker:

> truncated: <filename> at char_offset=N

where N is the character offset of the truncation point within the original file.

Step 7: Build Output Block (REQ-6, REQ-12, AC-6, AC-14)

Construct the consolidated context block. The first non-empty line must be exactly:

## Design Context (from .moai/design/)

For each included file, prepend a citation line:

> source: .moai/design/<filename>

then append the file content (or truncated content with the trailing marker).

If all candidate files were skipped (_TBD_-only) and no content was added, emit the header and log (REQ-15, AC-16):

design docs present but all are _TBD_ — no content loaded

Step 8: Return Result

Return the consolidated context block to the orchestrator for injection into the next subagent prompt.

If any warnings were collected (unreadable files), include a warnings section after the context block:

> warnings: [<token1> unreadable: <reason>, <token2> unreadable: <reason>]

Output Format Contract

## Design Context (from .moai/design/)

> source: .moai/design/spec.md
<content of spec.md>

> source: .moai/design/system.md
<content of system.md>

> source: .moai/design/research.md
<content of research.md — or truncated with marker>

> truncated: research.md at char_offset=12345

When .moai/design/ is absent or all files are _TBD_:

## Design Context (from .moai/design/)

Edge Cases

All Files Are TBD (REQ-15, AC-16)

Directory exists but every candidate is _TBD_-only. Return header with no > source: lines and log: design docs present but all are _TBD_ — no content loaded

Missing design_docs Configuration (REQ-16, AC-17)

design.yaml has no design_docs key. Use compiled-in defaults and log: design_docs not configured — using defaults

Standalone Invocation with Custom dir (REQ-10, AC-12)

When invoked with dir=/path/to/alt-design/, all Read tool calls must target paths under /path/to/alt-design/. Zero reads should target .moai/design/ in the project root.

Partial Read Failure (REQ-14, AC-15)

When one file is unreadable (permission error, corruption), add it to warnings, continue with remaining files, and include available > source: sections in the output.

Works Well With

• moai-domain-brand-design: Receives this skill's context block before brand design generation
• expert-frontend: Primary downstream consumer of injected context
• moai-workflow-design-import: Parallel path A workflow (Claude Design bundle)
• moai-workflow-gan-loop: Uses design context as quality evaluation reference

REQ coverage: REQ-1 through REQ-16 SPEC: SPEC-DESIGN-ATTACH-001 Version: 1.0.0