Improve task directory structure, design system integration, and TDD guidance

skills/build-unplanned-feature/SKILL.md

@@ -19,12 +19,30 @@ Extract the feature description from:
 
 Store the raw description for clarification.
 
-### Step 2: Clarify Requirements
+### Step 2: Load Existing Specs
+
+Before clarifying requirements, check for existing project specs so the clarification can detect contradictions and the implementation can follow established patterns.
+
+**Check for and read (if they exist):**
+- `specs/product_specs.md` (or `specs/product_specs/` directory) → `PRD_CONTEXT`
+- `specs/architecture.md` (or `specs/architecture/` directory) → `ARCHITECTURE_CONTEXT`
+- `specs/design_system.md` → `DESIGN_CONTEXT`
+
+For each, check single file first, then directory. If a directory, aggregate all `.md` files.
+
+If none exist, that's fine — proceed without them.
+
+### Step 3: Clarify Requirements
 
 **You MUST call the Skill tool now:** `Skill(skill="groundwork:understanding-feature-requests")`
 
 Do NOT attempt to gather requirements yourself. The skill handles this.
 
+If existing specs were loaded in Step 2, provide them as context to the clarification skill so it can:
+- Detect contradictions with existing PRD requirements
+- Identify overlap with existing features
+- Understand architectural constraints
+
 Follow the skill to gather:
 - Problem being solved
 - Target user/persona
@@ -33,7 +51,7 @@ Follow the skill to gather:
 
 Continue until requirements are clear and internally consistent.
 
-### Step 3: Generate Feature Identifier
+### Step 4: Generate Feature Identifier
 
 Create a feature identifier from the clarified requirements:
 
@@ -49,7 +67,7 @@ Create a feature identifier from the clarified requirements:
 - "Export reports to PDF" → `FEATURE-pdf-export`
 - "Rate limiting for API" → `FEATURE-api-rate-limit`
 
-### Step 4: Present Feature Summary
+### Step 5: Present Feature Summary
 
 Present summary to the user:
 
@@ -84,11 +102,11 @@ Then use `AskUserQuestion` to ask:
 
 **Wait for user response before proceeding.**
 
-### Step 5: Implementation (task-executor Agent)
+### Step 6: Implementation (task-executor Agent)
 
 Implementation is dispatched to the **task-executor agent** with a fresh context window. This agent has `implement-feature`, `use-git-worktree`, and `test-driven-development` skills preloaded — it does not need to call `Skill()` or spawn subagents.
 
-**Build the Task prompt with ALL gathered context from Steps 1-4.** You MUST include actual values, not placeholders:
+**Build the Task prompt with ALL gathered context from Steps 1-5 (specs from Step 2, requirements from Step 3, feature definition from Steps 4-5).** You MUST include actual values, not placeholders:
 
     Task(
       subagent_type="groundwork:task-executor:task-executor",
@@ -98,22 +116,35 @@ Implementation is dispatched to the **task-executor agent** with a fresh context
     PROJECT ROOT: [absolute path to project root]
 
     FEATURE DEFINITION:
-    - Identifier: [FEATURE-slug from Step 3]
-    - Title: [1-2 sentence summary from Step 4]
+    - Identifier: [FEATURE-slug from Step 4]
+    - Title: [1-2 sentence summary from Step 5]
 
     ACTION ITEMS:
-    [Bulleted list of requirements gathered in Steps 1-2]
+    [Bulleted list of requirements gathered in Steps 1-3]
 
     ACCEPTANCE CRITERIA:
-    [Bulleted list of acceptance criteria from Step 2/4]
+    [Bulleted list of acceptance criteria from Step 3/5]
 
     OUT OF SCOPE:
     [Bulleted list of exclusions, or 'None specified']
 
+    PROJECT CONTEXT (follow these established patterns):
+    [Include each section below ONLY if the spec was found in Step 2. Omit sections where no spec exists.]
+
+    ARCHITECTURE:
+    [Contents of ARCHITECTURE_CONTEXT — pay attention to technology choices, component boundaries, and decision records. Your implementation must follow these.]
+
+    DESIGN SYSTEM:
+    [Contents of DESIGN_CONTEXT — use these design tokens, patterns, and component styles. Do not invent new patterns that contradict the established system.]
+
+    EXISTING PRD (for reference only):
+    [Contents of PRD_CONTEXT — be aware of existing features to avoid duplication or contradiction. Do not re-implement existing functionality.]
+
     INSTRUCTIONS:
     1. Follow your preloaded skills to create a worktree, implement with TDD, and commit.
     2. The feature definition above provides all session context — do NOT re-ask the user for requirements.
-    3. When complete, output your final line in EXACTLY this format:
+    3. If project context is provided, follow the established architecture and design patterns.
+    4. When complete, output your final line in EXACTLY this format:
        RESULT: IMPLEMENTED | <worktree_path> | <branch> | <base_branch>
        OR:
        RESULT: FAILURE | [one-line reason]
@@ -130,11 +161,11 @@ Implementation is dispatched to the **task-executor agent** with a fresh context
 - `RESULT: FAILURE | ...` — Report the failure and worktree location for investigation, stop
 - No parseable RESULT line — Report: "Implementation subagent did not return a structured result. Check worktree status manually." Stop.
 
-### Step 6: Validation (Direct Skill Call)
+### Step 7: Validation (Direct Skill Call)
 
 **Call the validation-loop skill directly.** Do NOT wrap this in a subagent — this skill runs in the main conversation, which CAN spawn the 8 validation subagents it needs.
 
-1. `cd` into the worktree path from Step 5
+1. `cd` into the worktree path from Step 6
 2. Call: `Skill(skill='groundwork:validation-loop')`
 3. The validation-loop skill will run 8 verification agents in parallel and fix issues autonomously.
 
@@ -143,7 +174,7 @@ Implementation is dispatched to the **task-executor agent** with a fresh context
 - Validation failed → Report the failure and worktree location for investigation, stop
 - Stuck on recurring issue → Report the stuck finding and stop
 
-### Step 7: Merge Decision
+### Step 8: Merge Decision
 
 **From the project root** (NOT the worktree), handle merge:
 
@@ -191,7 +222,7 @@ cd .worktrees/<identifier>
 ```
 ```
 
-### Step 8: Report Completion
+### Step 9: Report Completion
 
 Output implementation summary:
 

skills/execute-task/SKILL.md

@@ -74,7 +74,7 @@ Read the tasks file from the worktree:
 
 Search for `### TASK-NNN:` pattern.
 
-**Error:** Task not found → "TASK-NNN not found in specs/tasks.md"
+**Error:** Task not found → "TASK-NNN not found in specs/tasks/"
 
 ### Step 3: Validate Task is Workable
 
@@ -105,9 +105,11 @@ Search for `### TASK-NNN:` pattern.
 Read from the worktree:
 1. **Product specs** - `specs/product_specs.md` or `specs/product_specs/`
 2. **Architecture** - `specs/architecture.md` or `specs/architecture/`
-3. **Tasks** - `specs/tasks.md` or `specs/tasks/`
+3. **Design system** - `specs/design_system.md` (if exists)
+4. **Tasks** - `specs/tasks.md` or `specs/tasks/`
 
 **If specs missing:** Report which are missing and suggest commands to create them.
+**If design system missing:** Not an error — proceed without it. Note its absence for the planner.
 
 ### Step 5: Plan Implementation
 
@@ -129,10 +131,14 @@ Relevant product specs:
 Relevant architecture:
 [extracted decisions]
 
+Design system:
+[extracted design tokens, color palette, typography, component patterns, UX patterns — or 'No design system defined' if not found]
+
 REQUIREMENTS FOR THE PLAN:
 1. All work happens in worktree .worktrees/TASK-NNN (not main workspace)
 2. Must follow TDD: write test → implement → verify cycle
 3. Plan covers implementation only — validation and merge are handled separately by the caller
+4. If a design system is provided and the task involves UI, the plan must reference specific design tokens, colors, and component patterns from it
 ",
   description="Plan TASK-NNN"
 )
@@ -191,7 +197,7 @@ Present summary to the user:
 
 ### Step 7: Implementation (task-executor Agent)
 
-1. **Update status** - Change task to `**Status:** In Progress`
+1. **Update status** - Change task file to `**Status:** In Progress` and update the status table in `specs/tasks/_index.md` (change the task's row to `In Progress`)
 
 2. **Dispatch to the task-executor agent** with a fresh context window. This agent has `implement-feature`, `use-git-worktree`, and `test-driven-development` skills preloaded — it does not need to call `Skill()` or spawn subagents.
 
@@ -319,7 +325,7 @@ cd .worktrees/TASK-NNN
 
 After successful merge or user acknowledgment:
 
-1. **Update status** - Change task to `**Status:** Complete`
+1. **Update status** - Change task file to `**Status:** Complete` and update the status table in `specs/tasks/_index.md` (change the task's row to `Complete`)
 
 ### Step 9: Complete and Report
 

skills/implement-feature/SKILL.md

@@ -77,6 +77,12 @@ For non-trivial changes, ask:
 
 If improvements identified: implement them (maintaining test coverage).
 
+### Step 4b: Frontend Visual Polish
+
+**For UI/frontend tasks**, apply visual polish before handing off. Read the design system spec (`specs/design_system.md`) if it exists.
+
+**Rule of thumb:** Every view should have at least one element that makes it visually distinctive. If everything is the same white card with the same border, it needs more visual variety.
+
 ### Step 5: Verify and Hand Off
 
 Verify all work before handing off:

skills/next-task/SKILL.md

@@ -7,26 +7,34 @@ user-invocable: false
 
 # Next Task Skill
 
-Finds the next uncompleted task from `specs/tasks.md` and delegates execution to the `execute-task` skill.
+Finds the next uncompleted task from `specs/tasks/` (or `specs/tasks.md`) and delegates execution to the `execute-task` skill.
 
 ## Workflow
 
 **IMPORTANT**: Your job is NOT to build a plan or build anything, it is to exclusively to find the next task to execute. Don't do planning or building until the full workflow is executed. If you find yourself planning or executing, STOP and follow the workflow.
 
-### Step 1: Load Tasks
+### Step 1: Load Task Index
 
-Read the tasks file to find available tasks:
-- Single file: `specs/tasks.md`
-- Directory: `specs/tasks/` (aggregated in sorted order)
+Read **only** the task index to find available tasks — do NOT read individual task files:
+- Directory mode: `specs/tasks/_index.md` (preferred — contains status table)
+- Single file fallback: `specs/tasks.md`
 
-**Detection:** Check for file first (takes precedence), then directory. When reading a directory, aggregate all `.md` files recursively with `_index.md` first, then numerically-prefixed files, then alphabetically.
+**Detection:** Check for `specs/tasks/_index.md` first, then `specs/tasks.md`. Do NOT aggregate all task files — the index contains the status table with all the information needed to find the next task.
 
 ### Step 2: Find Next Task
 
-Parse the tasks to find the next task to work on:
+Parse the status table in `_index.md` to find the next task:
 
-1. Look for all tasks with `**Status:** Not Started`
-2. Check dependencies - filter to unblocked tasks (no incomplete dependencies)
+```markdown
+| # | Task | Milestone | Status | Blocked by |
+|---|------|-----------|--------|------------|
+| TASK-001 | Auth setup | M1 | Complete | None |
+| TASK-002 | Login UI | M1 | In Progress | TASK-001 |
+| TASK-003 | Dashboard | M2 | Not Started | TASK-002 |
+```
+
+1. Look for all rows with Status = `Not Started`
+2. Check dependencies — filter to unblocked tasks (all tasks in `Blocked by` column are `Complete`)
 3. **Detect ambiguity:**
    - Let `candidates` = unblocked not-started tasks
    - Let `next_sequential` = lowest numbered candidate (e.g., TASK-004)
@@ -45,7 +53,9 @@ Parse the tasks to find the next task to work on:
 
 5. **If unambiguous:** Select the first unblocked, not-started task
 
-**Dependency check:** A task is blocked if its `Blocked by:` field lists any task that is not `Complete`.
+**Dependency check:** A task is blocked if its `Blocked by` column lists any task that is not `Complete` in the status table.
+
+**Fallback:** If `_index.md` has no status table, read individual task files to find statuses (legacy single-file format).
 
 **Tip:** For direct task selection, use `/groundwork:work-on N` to work on a specific task by number.
 
@@ -55,7 +65,7 @@ Parse the tasks to find the next task to work on:
 |-----------|----------|
 | No `specs/` directory | "No specs directory found. Run `/groundwork:design-product` to start defining your project." |
 | Missing tasks file | "Tasks file not found. Run `/groundwork:create-tasks` to generate tasks from your PRD and architecture." |
-| No tasks in file | "No tasks found in specs/tasks.md. The file may need to be regenerated with `/groundwork:create-tasks`." |
+| No tasks found | "No tasks found in specs/tasks/. The directory may need to be regenerated with `/groundwork:create-tasks`." |
 | All tasks complete | "All tasks complete! Consider running `/groundwork:source-product-specs-from-code` to update documentation or plan the next phase." |
 | Only blocked tasks | "All remaining tasks are blocked. Blocked tasks: [list]. Would you like to override and work on one anyway?" |
 | Parse error | "Could not parse tasks.md. Expected format: `### TASK-NNN: Title` with `**Status:**` field." |

skills/product-design/SKILL.md

@@ -21,10 +21,27 @@ Interactive workflow for iteratively designing and documenting product requireme
 
 If the user called the skill without any context, ask them to provide context on what feature they want to add, modify or remove.
 
+## Step 0.5: Load Project Context
+
+Before clarifying the request, load existing specs so you can detect contradictions and understand constraints:
+
+**Check for and read (if they exist):**
+- `specs/architecture.md` (or `specs/architecture/` directory) — technology choices, component boundaries, decision records. Use to catch architecturally infeasible requirements early.
+- `specs/design_system.md` — design principles, brand decisions, UX patterns. Use to ensure new features align with established design language.
+- `specs/product_specs.md` (or `specs/product_specs/` directory) — already loaded implicitly by the contradiction check, but read it explicitly here for full cross-feature context.
+
+For each, check single file first, then directory. If a directory, aggregate all `.md` files.
+
+If none exist, that's fine — proceed without them.
+
 ## Step 1: Understand the Request
 
 Invoke the `groundwork:understanding-feature-requests` skill to clarify the feature and check for contradictions.
 
+If architecture and design system were loaded in Step 0.5, provide them as context so the clarification can also check for:
+- **Architectural feasibility** — requirements that conflict with technology choices or component boundaries
+- **Design consistency** — features that would require patterns contradicting the established design system
+
 This skill will:
 1. Ask clarifying questions (core, exploratory, conditional)
 2. Check for internal, cross-feature, and technical contradictions
@@ -199,6 +216,10 @@ After successfully updating the PRD, use the `AskUserQuestion` tool to present t
         "label": "Design UX",
         "description": "Create user experience designs and flows for this feature"
       },
+      {
+        "label": "Create tasks",
+        "description": "Generate implementation tasks for this feature"
+      },
       {
         "label": "Add another feature",
         "description": "Continue adding more features to the PRD"
@@ -213,6 +234,7 @@ After successfully updating the PRD, use the `AskUserQuestion` tool to present t
 
 - **Design architecture**: Invoke the `groundwork:architecture` skill to design the technical approach
 - **Design UX**: Invoke the `groundwork:ux-design` skill to create UX designs
+- **Create tasks**: Invoke the `groundwork:tasks` skill to generate implementation tasks for the new feature
 - **Add another feature**: Clear context by summarizing what was just added, then restart from Step 1 with a fresh feature request. Ask: "What feature would you like to add next?"
 
 ## Conversation Patterns

skills/task-validation-loop/SKILL.md

@@ -11,7 +11,7 @@ Autonomous verification loop that runs 3 specialized agents to validate task lis
 ## Prerequisites
 
 Before invoking this skill, ensure:
-- Task list is complete (specs/tasks.md exists)
+- Task list is complete (specs/tasks/ directory or specs/tasks.md exists)
 - PRD exists (specs/product_specs.md)
 - Architecture exists (specs/architecture.md)
 - User has approved the task breakdown
@@ -93,7 +93,7 @@ Present results in table format:
    ```
 
 2. **Fix Each Finding** - Apply each critical/major recommendation
-   - Modify specs/tasks.md with required changes
+   - Modify the relevant task file in specs/tasks/ (or specs/tasks.md if single-file)
    - Track what was changed
    - Note which finding each fix addresses