ai-fob 1.3.0 → 1.3.2

package/assets/agents/build-validator-agent.md

@@ -26,6 +26,10 @@ You are a rigorous build validator. Your job is to run validation checks provide
 
 Run every validation check. Report exactly what you observe. If a check fails, describe the failure precisely -- what was expected vs. what actually happened. Do not attempt to fix the code or suggest fixes. Your report goes back to the orchestrator who will route failures to a builder agent for correction.
 
+## Browser Tool Constraint
+
+NEVER use the macOS `open` command to open URLs in a browser. ALWAYS use `agent-browser open <url>` for all browser-based checks. The `open` command launches Safari, which cannot be automated, snapshotted, or device-emulated. All browser interactions MUST go through `agent-browser` (Chromium via Playwright).
+
 ## Checks
 
 The calling prompt provides a numbered list of checks to run. Execute every check listed -- no more, no fewer. For each check:

package/assets/agents/explorer-agent.md

@@ -38,3 +38,4 @@ Present your findings as:
 - **Data Flow**: How data moves through the relevant files
 - **Integration Points**: Where new code would connect to existing code (file path + line)
 - **Shared Utilities**: Existing helpers, hooks, or patterns that should be reused
+- **File Size Audit**: List every key file with its line count. Flag files over 300 lines (warning) and over 500 lines (critical -- must be decomposed).

package/assets/commands/build-phase-V2.md

@@ -291,12 +291,13 @@ Run MARK_STEP_START(1).
    4. Shared utilities -- helpers, hooks, or patterns to reuse rather than rebuild
    5. Potential conflicts -- code this phase may need to modify that other work also touches
    6. Success criteria grounding -- for each success criterion, document what currently exists or is missing
+   7. File size audit -- for every file this phase will modify or extend, report its current line count. Flag files over 300 lines (WARNING) and over 500 lines (CRITICAL -- must be decomposed before adding code).
 
    Do NOT explore areas unrelated to this phase.
 
    ## Output
    Write your complete findings to: {PHASE_DIR}/explorer_findings.md
-   Structure your report with these sections: Prerequisites Status, Key Files, Existing Patterns, Integration Points, Shared Utilities, Potential Conflicts, Success Criteria Grounding, Data Flow.
+   Structure your report with these sections: Prerequisites Status, Key Files, Existing Patterns, Integration Points, Shared Utilities, Potential Conflicts, Success Criteria Grounding, Data Flow, File Size Audit.
    Write the file using the Write tool.
    Return the file path in your response.
    ```
@@ -417,6 +418,7 @@ After research is complete, spawn the architect agent to create the implementati
    - Every frontend domain MUST include `agent-browser` browser verification steps in the Phase Validation section. If the phase includes a Frontend domain, browser-based validation is MANDATORY, not optional.
    - This plan covers a SINGLE PHASE only -- do not plan work beyond this phase's scope
    - If the phase has multiple domains that can be built independently (no shared files, no cross-domain dependencies), mark them with `| PARALLEL` on the domain header line (e.g., `### Frontend | PARALLEL`). If uncertain, do NOT mark as parallel.
+   - NEVER plan to add significant logic to a file already over 300 lines without first splitting it into focused modules. Files over 500 lines MUST have a decomposition task BEFORE any new code is added. Check the Explorer's File Size Audit section for flagged files.
 
    ## Output Format
    Write the implementation plan in the Single-Phase Implementation Plan format (see below) to: {PHASE_DIR}/plan_V1.md
@@ -541,6 +543,7 @@ Anti-stories from the HL plan relevant to this phase:
 
 ## Important Notes
 [Gotchas, constraints, security considerations, version pinning, dependency ordering between tasks]
+[Flag any files from the File Size Audit that are over 300 lines and will be modified. Note decomposition strategy for any over 500 lines.]
 ```
 
 ### Step 3: Validate Plan (Correction Loop)
@@ -590,7 +593,7 @@ Read the plan at: {PHASE_DIR}/plan_V1.md
 ### Prior Phase Context
 {PRIOR_PHASE_CONTEXT if N > 1, otherwise "N/A -- this is Phase 1"}
 
-## Validation Checks (10 -- run ALL of these)
+## Validation Checks (11 -- run ALL of these)
 
 1. **File reference accuracy** -- Do referenced files, functions, and patterns actually exist in the codebase? Use Glob/Grep/Read to verify every file path mentioned in the plan. Flag any references to files, functions, or patterns that do not exist.
 
@@ -612,6 +615,8 @@ Read the plan at: {PHASE_DIR}/plan_V1.md
 
 10. **Self-containment check** -- Can a building agent execute this plan without further research? Verify all file paths to create/modify are explicit (no "find the appropriate file"). Verify code blocks are complete enough to implement (no "add similar logic here"). Verify dependency install commands are specified where new packages are introduced. Flag any task that requires the builder to make architectural decisions or do additional research.
 
+11. **File size check** -- Does the plan respect file size limits? Read the Explorer's File Size Audit section from `{PHASE_DIR}/explorer_findings.md`. For any file flagged over 300 lines that the plan modifies, verify the plan acknowledges the size concern (in Important Notes or as a refactoring task). For any file flagged over 500 lines, verify the plan includes an explicit decomposition task BEFORE adding new code to that file. FAIL if the plan adds code to a 500+ line file without decomposing it first.
+
 ## Validation Parameters
 - task: {TASK_NAME}
 - phase: {N}
@@ -621,7 +626,7 @@ Read the plan at: {PHASE_DIR}/plan_V1.md
 ## Output
 Write your validation report to: {PHASE_DIR}/plan_validation_report.md
 
-Use the YAML frontmatter format from your agent instructions with the parameters above. Include `checks-passed: X/10` in the frontmatter.
+Use the YAML frontmatter format from your agent instructions with the parameters above. Include `checks-passed: X/11` in the frontmatter.
 
 Write the file using the Write tool.
 Return the file path AND the overall result (pass or fail) in your response.
@@ -737,7 +742,7 @@ If validation has failed `MAX_CYCLES` (3) times, abort. Present:
 PLAN VALIDATION FAILED after 3 cycles. Aborting.
 
 Phase: {N} -- {PHASE_NAME}
-Checks passed: {X}/10 (cycle 3)
+Checks passed: {X}/11 (cycle 3)
 
 Remaining failures:
 - {check name -- problem summary}
@@ -903,9 +908,11 @@ Construct the final numbered check list by combining standard checks, plan-speci
 
 3. **Build succeeds** -- Run `./scripts/build.sh` via Bash. PASS if exit code is 0; FAIL if non-zero. Include the first 50 lines of output on failure.
 
+4. **No oversized files introduced** -- Identify files changed during this phase: if `git-available` is true, run `git diff --name-only {pre-phase-sha}..HEAD` via Bash to get the list of phase-modified files; if `git-available` is false, read the build report(s) and extract the "Files Created/Modified" lists. Then run `wc -l` on each identified file (skipping binary files and deleted files). PASS if all files are under 500 lines. FAIL listing each file that exceeds 500 lines with its line count. Also WARN (but do not FAIL) for files between 300-500 lines -- include these in the findings as advisories.
+
 **Plan-specific checks** (from `## Phase {N} Validation`):
 
-Number these sequentially starting at 4. Preserve the original check descriptions from the plan verbatim. For each check, the validator determines the check type (shell command, file verification, or browser verification) based on the description content.
+Number these sequentially starting at 5. Preserve the original check descriptions from the plan verbatim. For each check, the validator determines the check type (shell command, file verification, or browser verification) based on the description content.
 
 **Browser console error check** (always included AFTER plan-specific checks, but ONLY if any plan-specific check involves browser/UI verification OR the phase has a Frontend domain):
 
@@ -927,6 +934,12 @@ Store the total check count as `BUILD_CHECK_COUNT`. Store the count of HL criter
 
 Determine if browser checks exist: scan the assembled check list for any check that mentions "browser", "agent-browser", "navigate", "page", "UI", or "localhost". Store as `HAS_BROWSER_CHECKS` (true/false).
 
+If `HAS_BROWSER_CHECKS` is true: Read the Mobile Test Devices section from the testing-and-validation skill. Extract the Primary Device and Secondary Device values. Store as `MOBILE_PRIMARY_DEVICE` and `MOBILE_SECONDARY_DEVICE`. Determine `HAS_MOBILE_CHECKS`:
+- If `MOBILE_PRIMARY_DEVICE` is "NONE": set `HAS_MOBILE_CHECKS = false`.
+- Otherwise: set `HAS_MOBILE_CHECKS = true`.
+
+If `HAS_BROWSER_CHECKS` is false: set `HAS_MOBILE_CHECKS = false`.
+
 #### 5b. Start Dev Server (if needed)
 
 If `HAS_BROWSER_CHECKS` is true:
@@ -997,6 +1010,27 @@ Read the build report(s) for context on what was built:
  If Username is "REPLACE_WITH_TEST_USERNAME":
   "Test credentials have NOT been configured in the testing-and-validation skill. The placeholder values have not been replaced. Browser checks that require authentication MUST be marked as BLOCKED with reason: 'Test credentials not configured in testing-and-validation skill -- user must replace placeholder values.'"}
 
+## Mobile Device Testing
+{Read the Mobile Test Devices section from the testing-and-validation skill. Extract the Primary Device and Secondary Device values.
+
+ If HAS_MOBILE_CHECKS is true (Primary Device is NOT "NONE"):
+  "Mobile viewport testing is configured for this project. After completing each browser check at the default desktop viewport, you MUST repeat the visual/layout portions of that check at the mobile viewport.
+
+  Mobile testing procedure (use the agent-browser skill):
+  1. Complete the browser check at the default desktop viewport first
+  2. Set the mobile device: `agent-browser set device \"{MOBILE_PRIMARY_DEVICE}\"`
+  3. Reload the page: `agent-browser reload`
+  4. Take a snapshot to verify layout at mobile viewport: `agent-browser snapshot -i`
+  5. Take a screenshot for visual evidence: `agent-browser screenshot`
+  6. Verify the page renders correctly at the mobile viewport -- no overlapping elements, no horizontal scrolling, no truncated content, no inaccessible interactive elements
+  7. Reset to desktop viewport when done: `agent-browser set viewport 1920 1080`{If MOBILE_SECONDARY_DEVICE is not "NONE":
+  8. Repeat steps 2-7 with the secondary device: `agent-browser set device \"{MOBILE_SECONDARY_DEVICE}\"`}
+
+  For each browser check, report desktop and mobile results separately. If a check passes at desktop but fails at mobile, the overall check result is FAIL. Include the device name in the findings (e.g., 'FAIL at iPhone 12 Pro: navigation menu overlaps content')."
+
+ If HAS_MOBILE_CHECKS is false:
+  "Mobile viewport testing is not configured (Primary Device is NONE in the testing-and-validation skill). All browser checks run at the default desktop viewport only."}
+
 ## Validation Checks ({BUILD_CHECK_COUNT} -- run ALL of these)
 
 {The assembled numbered check list from step 5a -- paste the full list verbatim, including the [HL] prefixed checks at the end}
@@ -1019,6 +1053,8 @@ For each check, report one of three results:
 - phase-name: {PHASE_NAME}
 - cycle: {BUILD_VALIDATION_CYCLE}
 - hl-criteria-count: {HL_CRITERIA_COUNT}
+- pre-phase-sha: {PRE_PHASE_SHA}
+- git-available: {GIT_AVAILABLE}
 
 ## Output
 Write your validation report to: {PHASE_DIR}/build_validation_report.md
@@ -1309,7 +1345,7 @@ Implementation Plan Summary:
 - Source Citations: {count of `// per:` occurrences}
 
 Plan Validation: {VALIDATION_RESULT} (cycle {VALIDATION_CYCLE})
-- Checks passed: {X}/10
+- Checks passed: {X}/11
 
 Build Summary:
 - Builder(s): {BUILDER_COUNT} spawned {" (parallel)" if > 1}

package/assets/commands/create-highlevel-plan-phases.md

@@ -93,7 +93,8 @@ The user provided a feature document from a reverse-engineering analysis. Use it
    - **Name**: short descriptive name
    - **Goal**: 1-2 sentences on what this phase achieves and why it comes at this position
    - **Dependencies**: which prior phase(s) must complete first (or "None" for the first)
-   - **Success criteria**: concrete, verifiable statements (can be user stories, anti-stories, API checks, state checks, UI checks, build checks)
+   - **Success criteria**: concrete, verifiable statements (can be user stories, anti-stories, API checks, state checks, UI checks, build checks, mobile viewport checks)
+   - For phases with UI work, ask: "Does this need to work on mobile viewports?" If yes, include mobile-specific success criteria (e.g., "Navigation menu is usable on iPhone 12 Pro viewport")
    Target 3-5 phases. Present the suggested phases to the user:
    ```
    Based on the feature document, I suggest this phase breakdown:
@@ -155,7 +156,9 @@ The user provided a feature document from a reverse-engineering analysis. Use it
        - State/infrastructure checks: "Database tables exist and are accessible"
        - UI checks: "Login form renders with email and password fields"
        - Build/tooling checks: "`bun dev` starts without errors"
+       - Mobile viewport checks: "Navigation is usable at iPhone 12 Pro viewport"
    - For phases with user-facing behavior, success criteria MUST include both user stories (what users CAN do) and anti-stories (what users CANNOT do)
+   - For phases with UI work, ask the user: "Does this need to work on mobile viewports?" If yes, include mobile-specific success criteria. Mobile viewport testing is configured in the testing-and-validation skill.
    - Each criterion must be testable -- a future validator should be able to determine PASS/FAIL
    - The last phase should typically be "Integration & Polish"
 8. Do NOT proceed to Phase 2 until you and the user explicitly agree on the task description, user stories, anti-stories, phase breakdown, and detailed specifications (if any were provided).
@@ -180,6 +183,7 @@ Spawn a teammate using the `explorer-agent` agent definition. Include this conte
 - Anti-stories (from Phase 1)
 - Phase breakdown with success criteria (from Phase 1)
 - Specific areas of the codebase to focus on (if known)
+- Directive: "For every key file you report, include its line count. Flag any file over 300 lines as a WARNING and any file over 500 lines as CRITICAL -- these MUST be noted for the architect to plan decomposition."
 
 If IS_RE_ENGINEERING is true, also include in the Explorer's spawn prompt:
 - A note: "This task is a reimplementation based on a reverse-engineered feature document. The feature document describes how the original feature works in a different codebase. Your job is to explore THIS codebase (not the source repo at {SOURCE_REPO}) to understand what exists here that is relevant to building this feature."
@@ -214,6 +218,8 @@ Wait for the Explorer (and Docs Researcher if spawned) to complete their work. T
 
 Instruct the Architect to produce the plan in the specified format and post it to the shared task list. Instruct the Architect to preserve user-provided detailed specifications in the "Detailed Specifications" section of the plan (section 8) -- these are requirements, not implementation details.
 
+Instruct the Architect: "If the Explorer flagged any files over 300 lines, address them in Key Considerations (section 7). For files over 500 lines, the plan MUST include decomposition as an explicit task in the relevant phase. NEVER plan to add significant logic to a file already over 300 lines without first splitting it."
+
 #### If agent teams are NOT available (fallback):
 
 Use the Task tool to run these sequentially:
@@ -264,7 +270,7 @@ You are validating the high-level plan for {TASK_NAME}.
 Category: {task category}
 Description: {task description}
 
-## Validation Checks (9 -- run ALL of these)
+## Validation Checks (10 -- run ALL of these)
 
 1. **Current State accuracy** -- Does the plan's description of the codebase match reality? Use Grep/Glob to verify referenced files exist. Use Read to verify descriptions of file contents are accurate. Flag any references to files, functions, or patterns that don't exist.
 
@@ -284,6 +290,8 @@ Description: {task description}
 
 9. **Phase dependency ordering** -- Is the dependency chain a valid DAG? No circular dependencies. Does the ordering make logical sense? Can each phase start once its dependencies complete?
 
+10. **File size awareness** -- Does the plan address oversized files flagged by the Explorer? Check the Explorer's file size data. For any file over 300 lines that the plan modifies or extends, verify the plan acknowledges the size concern in Key Considerations (section 7). For any file over 500 lines, verify the plan includes explicit decomposition. Flag any plan that adds work to a 500+ line file without decomposing it first.
+
 ## Output
 Present the validation report directly in your response (or post to the shared task list if using agent teams).
 ```
@@ -421,6 +429,7 @@ Note: User-provided specifications (schemas, API requirements, business rules) a
 
 ## 7. Key Considerations
 Risks, gotchas, dependencies, things to watch out for. Include security considerations.
+Flag any existing files over 300 lines that this plan touches. Files over 500 lines MUST have a decomposition plan.
 These apply across all phases.
 
 ## 8. Detailed Specifications
@@ -461,7 +470,7 @@ Anti-Stories: {count}
 
 High-Level Approach: {1-2 sentence summary}
 Key Considerations: {count} identified
-Validation: PASSED ({count}/9 checks verified)
+Validation: PASSED ({count}/10 checks verified)
 
 State Files:
 - STATE.md: [read | scaffolded]
@@ -472,5 +481,5 @@ Team Members Used:
 - Explorer: completed
 - Docs Researcher: [completed | skipped]
 - Architect: completed ({N} iterations)
-- Validator: PASSED ({count}/9 checks verified)
+- Validator: PASSED ({count}/10 checks verified)
 ```

package/assets/commands/quick-fix.md

@@ -49,6 +49,11 @@ You are investigating a bug in this codebase.
    - Determine whether the issue is localized (single file/module) or cross-cutting (multiple layers/modules)
    - Note any architectural implications (data model changes, API surface changes, auth flow changes)
 
+4. Audit file sizes:
+   - For every affected file, count its lines using `wc -l`
+   - Flag any file over 300 lines as WARNING (risk of cascading bugs from changes)
+   - Flag any file over 500 lines as CRITICAL (file must be decomposed -- fix may cause more breakage)
+
 ## Output Format
 
 Report your findings with these sections:
@@ -58,6 +63,7 @@ Report your findings with these sections:
 - **Localized vs Cross-Cutting**: Is this a single-point fix or does it span multiple modules/layers?
 - **Architectural Implications**: Any data model, API, auth, or structural concerns (or "None")
 - **Relevant Patterns**: How similar code is handled correctly elsewhere in the codebase
+- **File Size Warnings**: Line counts of affected files. Flag any over 300 lines (WARNING) or over 500 lines (CRITICAL).
 
 Do NOT write your findings to a file. Return them directly.
 ```
@@ -107,6 +113,7 @@ Evaluate the following checklist against the research findings:
 - Change type is config, import, small logic fix, CSS/styling, typo, missing null check, or similar
 - No architectural implications (fix does not change data model, API surface, auth flow, or component hierarchy)
 - No risk of cascading side effects (change is localized)
+- No affected file exceeds 500 lines (from explorer's File Size Warnings -- oversized files have high cascading-bug risk)
 
 **Complex-Fix Indicators** (ANY triggers escalation):
 - Root cause is unclear or ambiguous after research
@@ -117,6 +124,7 @@ Evaluate the following checklist against the research findings:
 - Fix involves race conditions, concurrency, or timing issues
 - Research reveals the issue is a symptom of a deeper design problem
 - Fix requires changes across multiple layers (frontend + backend + database)
+- Any affected file exceeds 500 lines (oversized file -- high risk of cascading bugs; needs decomposition before fixing)
 
 Produce a triage verdict: **EASY** or **COMPLEX** with a one-line justification.
 
@@ -229,6 +237,7 @@ You MUST produce a plan using EXACTLY this format. No additional sections, no om
 - Keep it minimal -- this is a quick fix
 - The plan must address the root cause, not just the symptom
 - The verification step must be concrete and executable (a command to run, a test to check, a behavior to observe -- not "it should work now")
+- If any affected file is over 300 lines, note the file size risk in the Side Effects section. NEVER add significant logic to a file already over 300 lines without splitting it first.
 - Do NOT write the plan to a file. Return it directly.
 ```
 
@@ -289,6 +298,8 @@ For each cycle:
 - If the plan specifies a lint/type-check command: run it via Bash
 - If the plan specifies browser verification or manual UI checks: note this for the user in the final report (the main agent cannot do browser checks autonomously)
 
+**6c-pre. File size check**: For every file listed in "Files Affected", run `wc -l` via Bash. If any file exceeds 500 lines, report it as a WARNING in the final report with the message: "File {path} is {N} lines -- exceeds 500-line limit. Consider decomposition to prevent future cascading bugs." If any file exceeds 300 lines, note it as an advisory.
+
 **6c. Assess result**:
 - **PASS**: Verification succeeds (command exits 0, expected output matches). Proceed to Step 7.
 - **FAIL**: If VALIDATION_CYCLE < MAX_CYCLES:
@@ -345,6 +356,9 @@ Present the final report.
 
 ### Notes
 {Any caveats, things to watch for, or manual verification the user should do (e.g., browser checks noted in Step 6b)}
+
+### File Size Warnings
+{List any files over 300 lines from the file size check in Step 6c-pre, or "None -- all modified files are under 300 lines."}
 ```
 
 **If build validation FAILED after MAX_CYCLES:**

package/assets/skills/brainstorm-plan/reference/architecture-principles.md

@@ -56,6 +56,7 @@ Ask these questions about every proposed approach. The more "no" answers, the mo
 - [ ] Are there clear boundaries between this feature and the rest of the codebase?
 - [ ] Does this approach make future changes easier or harder?
 - [ ] Is the testing strategy straightforward?
+- [ ] Are individual files kept under 300 lines? Files over 300 lines are a warning sign; files over 500 lines MUST be decomposed before proceeding.
 
 ### Upgrade Path
 - [ ] Can the underlying framework/library be upgraded without rewriting this feature?
@@ -99,6 +100,12 @@ Watch for these patterns during brainstorming — they almost always indicate un
 - Caching everything by default instead of where profiling shows need
 - Choosing complex data structures for datasets under 1000 items
 
+### Oversized Files
+- Any single file exceeding 300 lines without a clear justification (warning threshold)
+- Any single file exceeding 500 lines regardless of justification (hard limit -- MUST be decomposed)
+- Putting multiple unrelated concerns in one file instead of splitting into focused modules
+- Growing an existing file rather than extracting a new module when adding features
+
 ## Paired Examples
 
 ### Example: User Preferences Storage

package/assets/skills/brainstorm-plan/workflows/quick-fix.md

@@ -70,6 +70,7 @@ ALL of the following must be true for a bug to qualify as an easy fix:
 - Change type is config, import, small logic fix, CSS/styling, typo, missing null check, or similar
 - No architectural implications (fix does not change data model, API surface, auth flow, or component hierarchy)
 - No risk of cascading side effects (change is localized)
+- No affected file exceeds 500 lines (oversized files have high risk of cascading bugs from even small changes)
 
 ### Complex-Fix Indicators
 
@@ -83,6 +84,7 @@ ANY of the following makes a bug complex (triggers escalation):
 - Fix involves race conditions, concurrency, or timing issues that need careful design
 - Research reveals the issue is a symptom of a deeper design problem
 - Fix requires changes across multiple layers (frontend + backend + database)
+- Any affected file exceeds 500 lines (oversized file -- high cascading-bug risk; needs decomposition before fixing)
 
 ## Lightweight Bug-Fix Plan Format
 

package/assets/skills/testing-and-validation/SKILL.md

@@ -58,6 +58,22 @@ Credentials for automated browser-based authentication. These are used by valida
 3. The Post-Login URL is the page the browser should land on after successful login -- used to confirm authentication succeeded
 4. If your app does not require authentication, set Username to `NONE` -- validators will skip the authentication step
 
+## Mobile Test Devices
+
+Device configurations for mobile viewport testing via Chrome DevTools device emulation (Playwright). These are used by validator agents to run browser checks at mobile viewports in addition to desktop. If your application has responsive layouts, configure a device here so automated tests verify mobile rendering.
+
+| Setting | Value |
+|---------|-------|
+| Primary Device | `iPhone 12 Pro` |
+| Secondary Device | `NONE` |
+
+**Setup instructions:**
+1. The Primary Device is the Chrome DevTools device name used for mobile viewport checks (e.g., `iPhone 12 Pro`, `Pixel 5`, `iPad Air`)
+2. The Secondary Device is an optional second device for additional viewport coverage. Set to `NONE` to skip.
+3. Device emulation is set via `agent-browser set device "{device name}"` before navigating to a page
+4. Reset to desktop after mobile checks with `agent-browser set viewport 1920 1080`
+5. If your app does not need mobile testing, set Primary Device to `NONE` -- validators will skip mobile viewport checks
+
 ## Front-End Testing
 
 For visual and interactive front-end testing, use the `agent-browser` skill.

package/assets/skills/workflow-repair/reports/2026-03-28_mobile-viewport-testing.md

@@ -0,0 +1,136 @@
+---
+type: diagnosis-report
+workflow: repair-workflow
+target-asset: .claude/skills/testing-and-validation/SKILL.md, .claude/commands/build-phase-V2.md, .claude/commands/create-highlevel-plan-phases.md, .claude/agents/build-validator-agent.md
+asset-type: skill, command, command, agent
+date: 2026-03-28
+status: validated
+failure-patterns: [Implicit Assumptions, Missing Guardrails]
+repair-strategies: [Explicit Instruction, Constraint Injection]
+root-cause-layer: Command-Layer
+---
+
+# Diagnosis Report: Mobile viewport testing absent from build validation pipeline
+
+## Problem Summary
+
+Mobile viewport validation never happened during build-phase-V2 browser checks -- all checks ran at the default desktop viewport only, missing responsive layout issues on smaller screens. Additionally, the build validator agent occasionally used the macOS `open` command (launching Safari) instead of `agent-browser open` (Chromium), creating unpredictable, unautomatable browser behavior. The root cause spans the full prompt chain: mobile testing intent was never captured during planning, no device configuration existed in the testing skill, and the build command never instructed the validator to set a mobile viewport.
+
+## Prompt Chain Trace
+
+### Command Markdown (Chain A: Planning)
+- **File**: `.claude/commands/create-highlevel-plan-phases.md`
+- **Finding**: ABSENT. Zero mentions of mobile, viewport, device, or responsive anywhere in the 477-line file. User story and success criteria sections never prompted for mobile testing needs. Because mobile intent was never captured, no mobile success criteria could flow downstream.
+
+### Command Markdown (Chain B: Validation)
+- **File**: `.claude/commands/build-phase-V2.md`
+- **Finding**: ABSENT. Browser check assembly (Step 5a) and validator delegation prompt (Step 5c) had no viewport/device instructions. The Test Credentials pattern existed and worked but was not replicated for device configuration.
+
+### Delegation Prompt Text
+- **Agent spawned**: build-validator-agent (via Step 5c of build-phase-V2)
+- **Finding**: ABSENT. The delegation prompt included dev server info and test credentials but no viewport/device configuration. Without instructions, the validator ran all browser checks at the default Chromium viewport.
+
+### Agent System Prompt
+- **File**: `.claude/agents/build-validator-agent.md`
+- **Finding**: ABSENT for mobile. The browser verification workflow (line 37) described navigate → snapshot → interact → re-snapshot but never mentioned setting a viewport. Also ABSENT for Safari guardrail: the agent had unrestricted `Bash` access with no prohibition on macOS `open`.
+
+### Skill Content
+- **Skills examined**: testing-and-validation, agent-browser
+- **Finding**: testing-and-validation INCOMPLETE -- mentioned "responsiveness" at line 71 but had no device config table. agent-browser PRESENT but UNUSED -- `set device` and `set viewport` commands were fully documented in references/commands.md but never invoked by any workflow.
+
+### Agent Behavior
+- **Observed**: Validator ran all browser checks at default desktop viewport. Occasionally used macOS `open` (Safari) instead of `agent-browser open` (Chromium).
+- **Expected**: Validator should also check at mobile viewport(s) when configured. Should always use `agent-browser open` for automatable, consistent browser testing.
+
+## Failure Pattern Classification
+
+### Primary Pattern: Implicit Assumptions
+- **Evidence**: The entire prompt chain implicitly assumed desktop-only browser testing was sufficient. The capability existed (`agent-browser set device`), the need existed (mobile layout issues), but no file in the chain connected them. The assumption was invisible because each file looked correct in isolation.
+- **Prompt chain link**: All links -- the assumption propagated through the entire chain from planning (no mobile question) through config (no device table) to validation (no viewport instructions).
+
+### Contributing Pattern: Missing Guardrails
+- **Evidence**: build-validator-agent had unrestricted `Bash` in its tools and no explicit prohibition on macOS `open`. The agent-browser skill's `allowed-tools: Bash(agent-browser:*)` was additive, not restrictive. The soft instruction at line 37 to use `agent-browser open` was insufficient.
+- **Prompt chain link**: Agent system prompt (build-validator-agent.md) -- missing negative constraint.
+
+## Root Cause Analysis
+
+- **Root cause layer**: Command-Layer (primary), Skill-Layer (contributing)
+- **Root cause description**: Both commands (create-highlevel-plan-phases and build-phase-V2) lacked workflow steps to establish and execute mobile testing. The planning command never asked about mobile viewports, so no mobile success criteria entered the plan. The build command never read device config or injected viewport instructions, so the validator had no reason to test at mobile dimensions. The testing-and-validation skill lacked a device configuration table, so even if the commands wanted to read config, there was nothing to read.
+- **Why shallow fixes failed**: N/A -- first repair attempt. However, fixing only build-phase-V2 would have been insufficient because mobile intent must originate at the planning level to flow into success criteria.
+
+## Impact Analysis
+
+- **Target assets**: `.claude/skills/testing-and-validation/SKILL.md`, `.claude/commands/build-phase-V2.md`, `.claude/commands/create-highlevel-plan-phases.md`, `.claude/agents/build-validator-agent.md`
+- **Blast radius**: Contained
+- **Affected consumers**: build-validator-agent (gains constraint + mobile config), setup-project.md (not modified -- new section not in its scope), plan-validator-agent (will see plans with mobile criteria -- no behavior change)
+- **High-risk aspects**: None. All changes are additive. Projects with Primary Device = `NONE` behave identically to before.
+
+## Repair Applied
+
+### Fix Specification
+- **Repair strategy**: Explicit Instruction
+- **Additional strategies**: Constraint Injection
+- **What was changed**: Added mobile device config table to testing-and-validation skill. Added mobile device detection and conditional testing instructions to build-phase-V2. Added mobile testing awareness prompts to create-highlevel-plan-phases (both paths). Added NEVER/ALWAYS Safari guardrail to build-validator-agent.
+- **File(s) modified**:
+  - `.claude/skills/testing-and-validation/SKILL.md`
+  - `.claude/commands/build-phase-V2.md`
+  - `.claude/commands/create-highlevel-plan-phases.md`
+  - `.claude/agents/build-validator-agent.md`
+
+### Fix Details
+
+6 changes across 4 files. Most significant change shown below.
+
+**Before** (build-phase-V2.md, after Test Credentials block):
+
+```
+ If Username is "REPLACE_WITH_TEST_USERNAME":
+  "Test credentials have NOT been configured..."}
+
+## Validation Checks ({BUILD_CHECK_COUNT} -- run ALL of these)
+```
+
+**After** (build-phase-V2.md, Mobile Device Testing block inserted):
+
+```
+ If Username is "REPLACE_WITH_TEST_USERNAME":
+  "Test credentials have NOT been configured..."}
+
+## Mobile Device Testing
+{Read the Mobile Test Devices section from the testing-and-validation skill.
+
+ If HAS_MOBILE_CHECKS is true (Primary Device is NOT "NONE"):
+  "Mobile viewport testing is configured. After completing each browser check at
+  desktop, you MUST repeat visual/layout checks at the mobile viewport.
+
+  Mobile testing procedure:
+  1. Complete desktop check first
+  2. Set mobile device: `agent-browser set device "{MOBILE_PRIMARY_DEVICE}"`
+  3. Reload: `agent-browser reload`
+  4. Snapshot: `agent-browser snapshot -i`
+  5. Screenshot: `agent-browser screenshot`
+  6. Verify: no overlapping elements, no horizontal scrolling, no truncated content
+  7. Reset to desktop: `agent-browser set viewport 1920 1080`
+
+  If a check passes at desktop but fails at mobile, overall result is FAIL."
+
+ If HAS_MOBILE_CHECKS is false:
+  "Mobile viewport testing is not configured. Desktop viewport only."}
+
+## Validation Checks ({BUILD_CHECK_COUNT} -- run ALL of these)
+```
+
+## Validation Results
+
+- **Fix addresses root cause**: Yes -- mobile testing is now explicitly wired through all 4 prompt chain links (planning → config → validation → agent constraint)
+- **No new failure patterns introduced**: Yes -- the `set device reset` issue caught during pre-implementation validation was corrected to `set viewport 1920 1080` before implementation
+- **Impact analysis clear**: Yes -- all consumers verified, no regressions found
+- **Test result**: Pass -- post-implementation validation passed 4/4 checks
+
+## Prevention Recommendations
+
+1. **Capability-to-instruction audit**: When a skill documents a capability (like `agent-browser set device`), trace every consuming command/agent and verify there is an explicit instruction to use it when relevant. Undocumented capabilities are dead weight.
+
+2. **Config table completeness check**: The testing-and-validation skill is the config hub for validators. New testing dimensions (mobile viewports, accessibility, performance budgets) should follow the established pattern: config table in skill → conditional read in build-phase-V2 Step 5a → conditional injection in Step 5c.
+
+3. **Negative constraint review for unrestricted Bash agents**: Any agent with `tools: Bash` should have explicit NEVER constraints for known-bad alternatives to intended tools (e.g., macOS `open` vs `agent-browser open`).

package/assets/supporting/hooks/session-start-model.sh

@@ -49,26 +49,12 @@ fi
 
 if [ "$should_check" = true ]; then
     (
-        # Read installed version from .ai-fob.json tracking file
-        current=""
-        # Check local project first, then global
-        for tracking in "$CLAUDE_PROJECT_DIR/.claude/.ai-fob.json" "$HOME/.claude/.ai-fob.json"; do
-            if [ -f "$tracking" ]; then
-                current=$(jq -r '.version // empty' "$tracking" 2>/dev/null)
-                [ -n "$current" ] && break
-            fi
-        done
-
-        if [ -z "$current" ]; then
-            exit 0
-        fi
-
-        # Query npm registry
+        # Query npm registry for latest version
         latest=$(npm view ai-fob version 2>/dev/null)
 
         if [ -n "$latest" ]; then
-            printf '{"current":"%s","latest":"%s","checked_at":%d}\n' \
-                "$current" "$latest" "$(date +%s)" > "$version_cache"
+            printf '{"latest":"%s","checked_at":%d}\n' \
+                "$latest" "$(date +%s)" > "$version_cache"
         fi
     ) &
 fi

package/assets/supporting/settings.json

@@ -1,6 +1,8 @@
 {
   "env": {
-    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
+    "CLAUDE_CODE_NO_FLICKER": "1",
+    "CLAUDE_CODE_SCROLL_SPEED": "1"
   },
   "statusLine": {
     "type": "command",

package/assets/supporting/statusline.sh

@@ -2,10 +2,12 @@
 
 # ai-fob status line for Claude Code
 # Reads JSON from stdin with workspace and context_window data
-# Displays: cwd, git branch, model, context bar + tokens, update indicator
+# Displays: cwd, git branch, update indicator, model, context bar + tokens
 
 input=$(cat)
 
+CACHE_DIR="$HOME/.claude/data/ai-fob-cache"
+
 # --- Working directory ---
 cwd=$(echo "$input" | jq -r '.workspace.current_dir')
 short_cwd=$(echo "$cwd" | sed "s|^$HOME|~|")
@@ -19,7 +21,30 @@ if git -C "$cwd" rev-parse --git-dir > /dev/null 2>&1; then
     fi
 fi
 
-# --- Extract context window size early (needed for model suffix + bar) ---
+# --- ai-fob update indicator (early so it's never truncated) ---
+update_display=""
+version_cache="$CACHE_DIR/version-check.json"
+if [ -f "$version_cache" ]; then
+    cached_ts=$(jq -r '.checked_at // 0' "$version_cache" 2>/dev/null)
+    now=$(date +%s)
+    age=$(( now - cached_ts ))
+    if [ "$age" -lt 3600 ]; then
+        latest_ver=$(jq -r '.latest // empty' "$version_cache" 2>/dev/null)
+        # Read installed version directly from .ai-fob.json (local first, then global)
+        current_ver=""
+        for tracking in "$cwd/.claude/.ai-fob.json" "$HOME/.claude/.ai-fob.json"; do
+            if [ -f "$tracking" ]; then
+                current_ver=$(jq -r '.version // empty' "$tracking" 2>/dev/null)
+                [ -n "$current_ver" ] && break
+            fi
+        done
+        if [ -n "$latest_ver" ] && [ -n "$current_ver" ] && [ "$latest_ver" != "$current_ver" ]; then
+            update_display=" \033[36m\xe2\xac\x86 ai-fob ${latest_ver}\033[0m"
+        fi
+    fi
+fi
+
+# --- Extract context window size (needed for model suffix + bar) ---
 usage=$(echo "$input" | jq '.context_window.current_usage')
 size=$(echo "$input" | jq '.context_window.context_window_size')
 current=0
@@ -28,7 +53,6 @@ if [ "$usage" != "null" ] && [ -n "$usage" ]; then
 fi
 
 # --- Model info (from session-start cache) ---
-CACHE_DIR="$HOME/.claude/data/ai-fob-cache"
 model_display=""
 session_id=$(echo "$input" | jq -r '.session_id // empty')
 
@@ -63,14 +87,24 @@ if [ -n "$model_display" ]; then
     model_display=" \033[35m${model_display}\033[0m"
 fi
 
-# --- Context window bar + percentage + total tokens ---
+# --- Context window bar + percentage + compact tokens ---
 context_display=""
 if [ "$usage" != "null" ] && [ -n "$usage" ] && [ "$size" != "null" ] && [ "$size" -gt 0 ] 2>/dev/null; then
     used=$((current * 100 / size))
 
-    # Format numbers with commas (bash builtin printf doesn't support %'d)
-    fmt_current=$(LC_ALL=en_US.UTF-8 /usr/bin/printf "%'d" "$current" 2>/dev/null || echo "$current")
-    fmt_size=$(LC_ALL=en_US.UTF-8 /usr/bin/printf "%'d" "$size" 2>/dev/null || echo "$size")
+    # Format numbers compactly (1M, 200K, etc.)
+    fmt_compact() {
+        local n=$1
+        if [ "$n" -ge 1000000 ]; then
+            echo "$((n / 1000000))M"
+        elif [ "$n" -ge 1000 ]; then
+            echo "$((n / 1000))K"
+        else
+            echo "$n"
+        fi
+    }
+    fmt_current=$(fmt_compact "$current")
+    fmt_size=$(fmt_compact "$size")
 
     # Build progress bar (10 segments)
     filled=$((used / 10))
@@ -79,32 +113,15 @@ if [ "$usage" != "null" ] && [ -n "$usage" ] && [ "$size" != "null" ] && [ "$siz
 
     # Color based on usage
     if [ "$used" -lt 50 ]; then
-        context_display=" \033[32m${bar} ${used}% ${fmt_current} of ${fmt_size}\033[0m"
+        context_display=" \033[32m${bar} ${used}% ${fmt_current}/${fmt_size}\033[0m"
     elif [ "$used" -lt 65 ]; then
-        context_display=" \033[33m${bar} ${used}% ${fmt_current} of ${fmt_size}\033[0m"
+        context_display=" \033[33m${bar} ${used}% ${fmt_current}/${fmt_size}\033[0m"
     elif [ "$used" -lt 80 ]; then
-        context_display=" \033[38;5;208m${bar} ${used}% ${fmt_current} of ${fmt_size}\033[0m"
+        context_display=" \033[38;5;208m${bar} ${used}% ${fmt_current}/${fmt_size}\033[0m"
     else
-        context_display=" \033[5;31m\xf0\x9f\x92\x80 ${bar} ${used}% ${fmt_current} of ${fmt_size}\033[0m"
-    fi
-fi
-
-# --- ai-fob update indicator ---
-update_display=""
-version_cache="$CACHE_DIR/version-check.json"
-if [ -f "$version_cache" ]; then
-    cached_ts=$(jq -r '.checked_at // 0' "$version_cache" 2>/dev/null)
-    now=$(date +%s)
-    age=$(( now - cached_ts ))
-    # Only use cache if less than 1 hour old
-    if [ "$age" -lt 3600 ]; then
-        latest_ver=$(jq -r '.latest // empty' "$version_cache" 2>/dev/null)
-        current_ver=$(jq -r '.current // empty' "$version_cache" 2>/dev/null)
-        if [ -n "$latest_ver" ] && [ -n "$current_ver" ] && [ "$latest_ver" != "$current_ver" ]; then
-            update_display=" \033[36m\xe2\xac\x86 ai-fob ${latest_ver}\033[0m"
-        fi
+        context_display=" \033[5;31m\xf0\x9f\x92\x80 ${bar} ${used}% ${fmt_current}/${fmt_size}\033[0m"
     fi
 fi
 
-# --- Output ---
-printf '%s%s%b%b%b' "$short_cwd" "$git_branch" "$model_display" "$context_display" "$update_display"
+# --- Output: cwd (branch) [update] model bar% tokens ---
+printf '%s%s%b%b%b' "$short_cwd" "$git_branch" "$update_display" "$model_display" "$context_display"

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.3.0",
+  "version": "1.3.2",
   "presets": {
     "coding": {
       "description": "Research-driven coding workflow",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-fob",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Deploy research-driven AI coding assistant assets (skills, agents, commands) into your projects",
   "bin": {
     "ai-fob": "bin/install.js"