opencastle 0.31.6 → 0.32.0

package/src/dashboard/src/styles/dashboard.css

@@ -2735,3 +2735,88 @@ body {
     max-width: 180px;
   }
 }
+
+/* Waiting for convoy banner */
+.waiting-banner {
+  text-align: center;
+  padding: 3rem 2rem;
+  margin-bottom: 2rem;
+  border-radius: var(--radius-lg, 12px);
+  background: var(--bg-surface, #1e1e2e);
+  border: 1px solid var(--border-subtle, rgba(255,255,255,0.06));
+}
+.waiting-banner__content {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.75rem;
+}
+.waiting-banner__spinner {
+  width: 32px;
+  height: 32px;
+  border: 3px solid var(--border-subtle, rgba(255,255,255,0.1));
+  border-top-color: var(--accent, #60a5fa);
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+}
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+.waiting-banner__title {
+  font-size: 1.25rem;
+  font-weight: 600;
+  margin: 0;
+  color: var(--text-primary, #e2e8f0);
+}
+.waiting-banner__subtitle {
+  font-size: 0.875rem;
+  color: var(--text-muted, #94a3b8);
+  margin: 0;
+}
+
+/* Pipeline chain navigation */
+.pipeline-chain-nav {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem 0;
+  margin-bottom: 0.5rem;
+  flex-wrap: wrap;
+}
+.pipeline-chain__label {
+  font-size: 0.75rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-muted, #94a3b8);
+  margin-right: 0.25rem;
+}
+.pipeline-chain__item {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  padding: 0.25rem 0.625rem;
+  font-size: 0.8125rem;
+  border-radius: var(--radius-sm, 6px);
+  border: 1px solid var(--border-subtle, rgba(255,255,255,0.06));
+  background: var(--bg-surface, #1e1e2e);
+  color: var(--text-secondary, #cbd5e1);
+  cursor: pointer;
+  transition: border-color 0.15s, background 0.15s;
+}
+.pipeline-chain__item:hover {
+  border-color: var(--border-hover, rgba(255,255,255,0.15));
+  background: var(--bg-hover, rgba(255,255,255,0.04));
+}
+.pipeline-chain__item--active {
+  border-color: var(--accent, #60a5fa);
+  background: rgba(96, 165, 250, 0.08);
+  color: var(--text-primary, #e2e8f0);
+}
+.pipeline-chain__dot {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}

package/src/orchestrator/agents/developer.agent.md

@@ -33,6 +33,14 @@ After code changes, always run lint, test, and build for affected projects.
 - Co-locate component files (component, styles, tests) in the same directory
 - Place shared components in the UI library, queries in the data layer
 
+### Multi-Page Convoy Consistency
+
+When working on a page task within a multi-agent convoy:
+- **Import** design tokens, layout component, and UI components from the foundation — do not recreate them
+- **Follow** the aesthetic direction and content tone specified in your task prompt's Foundation References
+- If a needed design token is missing, flag it in your output — never add inline values as workarounds
+- Load the **project-consistency** skill for the full consistency contract
+
 ## Done When
 
 - All acceptance criteria from the tracker issue are met

package/src/orchestrator/agents/ui-ux-expert.agent.md

@@ -32,6 +32,13 @@ Resolve all skills (slots and direct) via [skill-matrix.json](.opencastle/agents
 - Use `clsx` for conditional class composition
 - Export all components from the UI library's index
 
+### Multi-Page Convoy Consistency
+
+When working on a page task within a multi-agent convoy:
+- **If you are the foundation task:** create comprehensive design tokens, shared layout, and UI component library. Your choices become the project contract — be explicit and decisive.
+- **If you are a page task:** consume the foundation. Import tokens, layout, and UI components — do not recreate them. No new design values.
+- Load the **project-consistency** skill for full guidance on foundation artifacts and page task rules.
+
 ## Done When
 
 - Components render correctly at all project-defined responsive breakpoints

package/src/orchestrator/prompts/assess-complexity.prompt.md

@@ -43,6 +43,14 @@ Analyze the PRD below and produce a complexity assessment as a **single JSON obj
       "phases": [<phase numbers>],
       "depends_on": ["<group name>", ...]
     }
+  ],
+  "task_complexity": [
+    {
+      "workstream": "<workstream title from PRD Task Breakdown>",
+      "phase": <phase number>,
+      "complexity": 1 | 2 | 3 | 5 | 8 | 13,
+      "rationale": "<brief reason>"
+    }
   ]
 }
 ```
@@ -65,3 +73,8 @@ Analyze the PRD below and produce a complexity assessment as a **single JSON obj
   - **Minimum 3 tasks per group.** Never create a group that would produce a convoy with only 1–2 tasks — merge small groups with adjacent ones. A convoy with a single task is pointless overhead.
   - **Do NOT map phases 1:1 to groups.** Groups should bundle multiple related phases when tasks are tightly coupled (e.g., config + data in one group, components + pages in another). Only split at genuine domain boundaries where failure isolation matters.
   - Maximum 3 groups for projects with ≤ 15 tasks. Maximum 4 groups for 16+ tasks.
+- `task_complexity`: Array of per-workstream complexity assessments using Fibonacci scale.
+  - `workstream`: Exact workstream title from the PRD's Task Breakdown section.
+  - `phase`: Phase number the workstream belongs to.
+  - `complexity`: Fibonacci score: `1` (trivial — single file edit), `2` (simple — small fix, one test), `3` (moderate — new component/endpoint), `5` (significant — multi-file feature), `8` (complex — cross-cutting), `13` (epic — architecture-level).
+  - `rationale`: One sentence explaining the score.

package/src/orchestrator/prompts/brainstorm.prompt.md

@@ -73,6 +73,18 @@ Draw a clear boundary:
 - **Out of scope:** What it explicitly will NOT do (and why)
 - **Deferred:** What could be done later as a follow-up
 
+#### Design Direction (for multi-page projects)
+
+If the request involves building 2+ pages or UI sections, define the design direction during brainstorming — not during implementation:
+
+- **Aesthetic direction:** 2-3 words (e.g., "warm editorial", "clean minimal", "brutalist edge")
+- **Typography pairing:** display font + body font (avoid generic defaults like Inter/Roboto)
+- **Color intent:** dominant purpose, accent purpose, mood
+- **Content tone:** formal/casual, active/passive, target audience voice
+- **Key terminology:** terms that could be said multiple ways — pick one (e.g., "projects" not "portfolio")
+
+Include this in the Brainstorm Report so the planning phase can inject it into convoy foundation tasks.
+
 ### 6. Output
 
 Summarize the brainstorm as a **Brainstorm Report** — this becomes the input for the planning/decomposition phase:
@@ -98,6 +110,12 @@ Summarize the brainstorm as a **Brainstorm Report** — this becomes the input f
 
 ### Open Questions
 - [Any unresolved questions for the user]
+
+### Design Direction (if multi-page)
+- **Aesthetic:** [direction]
+- **Typography:** [display font] + [body font]
+- **Tone:** [description]
+- **Key terms:** [glossary]
 ```
 
 ## When to Skip Brainstorming

package/src/orchestrator/prompts/generate-convoy.prompt.md

@@ -52,6 +52,13 @@ You are the Team Lead. The user wants to run `opencastle run` to execute a batch
 | `max_retries` | integer | no | Override retry count for this task |
 | `review` | `fast` \| `panel` \| `none` \| `auto` | no | Review level |
 | `gates` | list of strings | no | Per-task gate commands |
+| `complexity` | `1` \| `2` \| `3` \| `5` \| `8` \| `13` | no | Fibonacci complexity score. Auto-populates timeout/retries/review from effort table. |
+
+### Complexity Scores
+
+If a **Pre-Computed Task Complexity** table is present in the context, use those scores directly — do not re-derive them. Map each convoy task to the closest workstream; for combined workstreams use the highest score.
+
+If no pre-computed data is available, assess complexity yourself: `1` (trivial), `2` (simple), `3` (moderate), `5` (significant), `8` (complex), `13` (epic).
 
 ### Agent Roster
 
@@ -93,6 +100,39 @@ For each workstream, break it down into the smallest meaningful unit. Follow the
 5. **Appropriate agent** — pick the agent whose speciality matches the task (e.g. `testing-expert` for tests, `database-engineer` for migrations).
 6. **Realistic timeouts** — `30m` for most tasks; `1h` for large refactors; `10m` for small docs or config.
 
+### 2.5 Foundation Phase for Multi-Page Projects
+
+When the goal involves building **2 or more pages, views, or UI sections**, apply the Foundation-First Pattern to prevent consistency drift across parallel agents:
+
+1. **Create a foundation task** (`id: foundation-setup`) as the FIRST task. This task:
+   - Creates a **design tokens file** (CSS custom properties for colors, typography, spacing, motion, shadows, breakpoints)
+   - Creates a **shared layout component** (page container with header, footer, navigation)
+   - Creates a **UI component library** (Button, Card, Heading, Text, Section, Container, Grid)
+   - Establishes the **style guide** (aesthetic direction, content tone, terminology, navigation labels)
+   - Agent: `ui-ux-expert` or `developer`
+
+2. **All page tasks must `depends_on: [foundation-setup]`** — they cannot run until the foundation is in place.
+
+3. **Every page task prompt must include Foundation References** — these 5 mandatory lines constrain the agent to `use` existing artifacts instead of `creating` new ones:
+   ```
+   ### Foundation References (MANDATORY)
+   - Design tokens: `[path to tokens file]` — use ONLY these variables. No new color/font/spacing values.
+   - Layout: `[path to Layout component]` — wrap all content in this layout.
+   - UI components: `[path to ui/ directory]` — import shared components. Do not recreate Button/Card/etc.
+   - Aesthetic: [2-3 word direction from foundation]
+   - Tone: [content tone from foundation]
+   ```
+
+4. **The foundation prompt itself** should specify:
+   - The aesthetic direction (2-3 words + elaboration)
+   - The typography pairing (display + body font)
+   - The color palette intent (dominant, accent, muted)
+   - The navigation labels (exact text for every nav link)
+   - The content tone (formal/casual, active/passive)
+   - Terminology choices (e.g., "projects" not "portfolio")
+
+> **Why:** Without this pattern, parallel agents independently choose fonts, colors, component APIs, and content tone. The result looks like it was built by different teams — because it was. Foundation-first makes consistency structural, not aspirational.
+
 ### 3. Define the Dependency Graph (DAG)
 
 - Tasks with no dependencies run first (in parallel up to `concurrency`).
@@ -127,6 +167,12 @@ Each task `prompt` must be a **complete, standalone instruction**. Include:
 >
 > **Strong prompt:** "Write unit tests for `libs/auth/src/server.ts` covering token refresh, expiry edge cases, and invalid signatures. Place tests in `libs/auth/src/__tests__/server.test.ts`. Follow the existing test conventions. Achieve ≥ 95% coverage for `server.ts`. Run the project's test command with coverage and fix any failures."
 
+> **Multi-page prompt pattern:** For page tasks in a multi-page project, always include the Foundation References block (from Step 2.5). The foundation task creates the design system; page tasks consume it.
+>
+> **Strong page prompt:** "Build the About page at `app/about/page.tsx`. **Foundation References:** Design tokens: `src/styles/tokens.css` — use ONLY these variables. Layout: `src/components/Layout.tsx` — wrap content in this layout. UI components: `src/components/ui/` — use Heading, Text, Section. Aesthetic: warm editorial. Tone: conversational and authentic. Include a bio section, skills grid (use Card from UI lib), and a timeline of experience. Responsive at 320px, 768px, 1280px."
+>
+> **Weak page prompt:** "Build the About page with a bio and skills section." — No foundation references, agent will create its own styles.
+
 ### 6. Validate Before Outputting
 
 - [ ] Every task has a unique `id`
@@ -141,6 +187,9 @@ Each task `prompt` must be a **complete, standalone instruction**. Include:
 - [ ] **File list completeness**: Every file mentioned in a task's prompt that the agent will create or modify MUST appear in that task's `files` list. Don't omit utility files, sub-components, or config files if the prompt instructs the agent to create them.
 - [ ] **Prompt instruction accuracy**: Don't include instructions that contradict the dependency graph. If a task depends on another task (via `depends_on`), the depended task's outputs will exist when this task runs — don't add `@ts-expect-error` comments, stub files, or "if not found" fallbacks for files produced by dependencies.
 - [ ] **Content research rule compliance**: If a prompt concerns real people, places, or organisations, it includes a research instruction telling the agent to search the internet first.
+- [ ] **Foundation phase present**: If the plan involves 2+ pages or UI sections, a `foundation-setup` task exists with no dependencies, and all page tasks depend on it
+- [ ] **Foundation references in page prompts**: Every page-building task prompt includes the 5 mandatory Foundation References (design tokens path, layout path, UI component path, aesthetic direction, content tone)
+- [ ] **No token duplication**: Page task prompts do NOT instruct agents to create new design tokens, layout components, or shared UI primitives — only to import and use existing ones from the foundation
 
 ### 7. Output
 
@@ -184,3 +233,15 @@ When chain mode is detected:
 }
 ````
 
+## Historical Performance Context
+
+When historical execution data is available (via `opencastle insights --json`), the Team Lead should include a compact summary in the context. Example:
+
+### Historical Performance (auto-generated)
+Based on {N} past convoys:
+- Tasks on `src/cli/` succeed 92% with Developer (avg 8min)
+- Recommended concurrency for {task_count} tasks: {recommended}
+- Agents to watch: {high_retry_agents}
+
+Use this data to make evidence-based decisions about agent assignment, concurrency, and timeout settings.
+

package/src/orchestrator/skills/decomposition/SKILL.md

@@ -121,3 +121,38 @@ Phase 4 (background):    Validation — Security audit + Tests + Docs (parallel)
 Phase 5 (sub-agent):     QA gate — verify all phases, run builds, self-review
 Phase 6 (sub-agent):     Panel review — load panel-majority-vote skill for high-stakes validation
 ```
+
+## Foundation-First Decomposition
+
+When decomposing a multi-page or multi-component project, always apply the Foundation-First Pattern to maintain cross-agent consistency:
+
+### When to apply
+
+- Goal involves 2+ pages, views, or UI sections
+- Multiple agents (same or different phase) will produce visual output
+- The project doesn't have an existing design system
+
+### Phase structure
+
+```
+Phase 1: foundation-setup
+├── Creates: design tokens, layout, UI component library
+├── Defines: style guide brief (aesthetic, tone, terminology)
+└── All visual tasks → depends_on: [foundation-setup]
+
+Phase 2+: page tasks (parallel)
+├── Each prompt includes 5 Foundation References
+└── Agents consume tokens — never create new values
+```
+
+### Partition rules for foundation
+
+- Foundation task owns: `src/styles/`, `src/components/Layout.*`, `src/components/ui/`
+- Page tasks own: their specific page file + page-specific components only
+- No page task may list a foundation-owned path in its `files[]`
+
+### Common mistake
+
+Decomposing pages as independent Phase 1 tasks (no foundation). This produces partition-clean, dependency-valid specs that fail aesthetically — each agent invents its own design. Always add the foundation task as the root of the DAG for visual work.
+
+> Load the **project-consistency** skill for the full Foundation Phase pattern, prompt templates, and anti-patterns.

package/src/orchestrator/skills/frontend-design/SKILL.md

@@ -192,4 +192,30 @@ Run this checklist before delivering any frontend work. Every item is a gate —
 - [ ] No hardcoded widths that break at unexpected viewports
 - [ ] Images and decorative elements have proper `alt` text or `aria-hidden`
 - [ ] Focus indicators are visible and styled to match the aesthetic
-- [ ] Performance: no layout thrashing from scroll-triggered animations without `will-change`
+- [ ] Performance: no layout thrashing from scroll-triggered animations without `will-change`
+## Convoy-Aware Design
+
+When building as part of a multi-agent convoy (multiple pages or sections built in parallel), additional rules apply:
+
+### If you ARE the foundation task agent
+
+You are establishing the design system for the entire project. Your output is the source of truth that all other agents will consume. Focus on:
+
+1. **Design tokens file** — comprehensive CSS custom properties covering all visual dimensions
+2. **Layout component** — shared page container used by every page
+3. **UI component library** — shared primitives (Button, Card, Heading, etc.)
+4. **Style guide brief** — aesthetic direction, content tone, terminology, nav labels
+
+Make explicit, decisive choices. Ambiguity in the foundation cascades into inconsistency across pages.
+
+### If you are a page task agent (consuming the foundation)
+
+You are NOT making design decisions — you are executing within an established system.
+
+- **Import** design tokens. **Do not** create new color values, font sizes, or spacing units.
+- **Import** the Layout component. **Do not** create a page-local layout wrapper.
+- **Import** UI components (Button, Card, etc.). **Do not** recreate them.
+- **Follow** the aesthetic direction and content tone from the foundation.
+- If a token you need doesn't exist, flag it in your output — NEVER add an inline value as a workaround.
+
+> Load the **project-consistency** skill for the full Foundation Phase pattern and prompt templates.