ac-framework 1.9.4 → 1.9.6

package/framework/mobile_development/.crush/commands/opsx/ac.md

@@ -10,132 +10,168 @@ If you attempt to proceed without completing a required step, you MUST STOP and
 
 ## Available Skills
 
-### Quality and Security Skills
+### AC Framework Core Skills
 
 | Skill | Description | Primary Use | Required Before |
 |-------|-------------|-------------|-----------------|
-| `secure-coding-cybersecurity` | Detects and prevents security vulnerabilities (SQLi, XSS, command injection, hardcoded secrets). Follows OWASP Top 10 standards. | Secure code validation | `code-maintainability` |
-| `code-maintainability` | Analyzes code maintainability: duplication, documentation, error handling, naming conventions, SOLID architecture, performance. | Refactoring and standards | `project-constitution` |
-| `error-handling-patterns` | Error handling patterns in multiple languages: exceptions, Result types, retry, circuit breaker, graceful degradation. | Application resilience | `secure-coding-cybersecurity` |
-| `performance-optimizer` | Methodologies for measuring, profiling, and optimizing code (caching, algorithm complexity, resource usage). | Performance Engineering | After Implementation |
-| `test-generator` | Generate comprehensive test suites (Unit, Integration, E2E) ensuring requirements are met. | Test Driven Development | `openspec-continue-change` |
+| `acfm-spec-workflow` | **START HERE - MANDATORY**. Understand spec-driven workflow, `.acfm/` vs `openspec/`, and required CLI commands. | Foundation | **ANYTHING ELSE** |
+| `acfm-memory` | **PERSISTENT MEMORY PROTOCOL**. Recall project context on session start and save reusable decisions/patterns after significant work. | Knowledge persistence | Session start and after significant work |
+
+### OpenSpec Workflow Skills
 
-### SpecKit Consistency & Quality Skills
+| Skill | Description | Primary Use | Required Before |
+|-------|-------------|-------------|-----------------|
+| `openspec-explore` | Explore architecture, constraints, and integration points before committing implementation details. | Pre-analysis | `acfm-spec-workflow` |
+| `openspec-new-change` | Start a new change with structured artifacts. | Structured start | `brainstorming` |
+| `openspec-ff-change` | Fast-forward artifact creation when speed is needed and scope is clear. | Accelerated start | `brainstorming` |
+| `openspec-continue-change` | Continue artifact generation in sequence (proposal/specs/design/tasks). | Workflow continuation | `openspec-new-change` OR `microtask-decomposition` |
+| `openspec-apply-change` | Implement tasks from artifacts. | Implementation | `openspec-continue-change` |
+| `openspec-verify-change` | Verify implementation against artifacts. | Validation | `openspec-apply-change` |
+| `openspec-sync-specs` | Merge delta specs to main specs without archiving. | Spec synchronization | `openspec-verify-change` |
+| `openspec-archive-change` | Archive completed change. | Change closure | `openspec-verify-change` |
+| `openspec-bulk-archive-change` | Archive multiple completed changes. | Batch closure | `openspec-verify-change` |
+| `openspec-onboard` | Guided walkthrough to learn full OpenSpec lifecycle. | Learning | `acfm-spec-workflow` |
+
+### Spec and Planning Skills
 
 | Skill | Description | Primary Use | Required Before |
 |-------|-------------|-------------|-----------------|
-| `project-constitution` | Manage the project's core principles and ensuring alignment. | Project Governance | **PHASE 1 START** |
-| `requirement-checklist` | Generate quality control checklists for requirements (unit tests for specs). | Requirements Quality | `spec-clarification` |
-| `spec-analysis` | Analyze consistency across Spec, Plan, and Tasks. | Consistency Check | `openspec-continue-change` |
-| `spec-clarification` | Interactively clarify specific sections of the spec. | Ambiguity Resolution | `openspec-new-change` |
+| `project-constitution` | Define and maintain core project principles. | Governance | **PHASE 1 START** |
+| `project-index` | Map codebase structure and document domains/agent guidance. | Context mapping | `project-constitution` |
+| `context-synthesizer` | Maintain continuity in long sessions and multi-change efforts. | Context management | `project-constitution` |
+| `research-retrieval` | Pull external references and technical docs. | Research | `openspec-explore` |
+| `brainstorming` | Generate all key questions up front to reduce hidden assumptions. | Design thinking | `openspec-explore` |
+| `spec-clarification` | Resolve ambiguity in specs with targeted clarifications. | Requirement clarity | `openspec-new-change` |
+| `spec-analysis` | Check consistency across proposal/specs/design/tasks. | Consistency check | `openspec-continue-change` |
+| `microtask-decomposition` | Split complex tasks into smaller executable microtasks (only when needed). | Advanced decomposition | `openspec-continue-change` |
 
-### Planning and Design Skills
+### Mobile Platform and Stack Skills
 
 | Skill | Description | Primary Use | Required Before |
 |-------|-------------|-------------|-----------------|
-| `brainstorming` | Generates ALL questions at once about decisions before implementing. Explores requirements, constraints, and success criteria in a SINGLE comprehensive prompt. | Design and architecture | `openspec-explore` |
-| `api-design-principles` | REST and GraphQL design principles: resources, endpoints, pagination, versioning, HATEOAS. | API design | `spec-clarification` [IF APIs] |
-| `interface-design` | Interface design (dashboards, admin panels, apps). NOT for landing pages/marketing. | UI design | `spec-clarification` [IF UI] |
+| `mobile-design` | Mobile-first doctrine: touch, performance, offline, platform behavior. | Baseline mobile standards | `project-constitution` |
+| `mobile-ios-design` | iOS HIG-driven UI/UX guidance and SwiftUI-oriented patterns. | iOS interface design | `spec-clarification` [IF iOS UI] |
+| `mobile-android-design` | Material 3 and Android UX patterns. | Android interface design | `spec-clarification` [IF Android UI] |
+| `react-native-design` | React Native layout, animation, navigation, and mobile UX design. | RN UI design | `spec-clarification` [IF React Native] |
+| `react-native-architecture` | React Native architecture, native modules, offline/data boundaries. | RN architecture | `spec-clarification` [IF React Native] |
+| `react-state-management` | Choose and implement robust state strategy (Redux Toolkit/Zustand/Jotai/etc.). | RN/React state design | `spec-clarification` [IF complex state] |
+| `flutter-expert` | Flutter/Dart architecture and implementation guidance. | Flutter implementation | `spec-clarification` [IF Flutter] |
+| `ios-developer` | Native iOS engineering (Swift/SwiftUI/UIKit, platform integration). | Native iOS implementation | `spec-clarification` [IF native iOS] |
 
-### AC Framework Core Skills
+### Delivery and Support Skills
 
 | Skill | Description | Primary Use | Required Before |
 |-------|-------------|-------------|-----------------|
-| `acfm-spec-workflow` | **START HERE - MANDATORY** - Understand the spec-driven workflow, directory structure (.acfm/ vs openspec/), and CLI commands. Essential before using any OpenSpec skills. | Foundation | **ANYTHING ELSE** |
-| `acfm-memory` | **PERSISTENT MEMORY PROTOCOL** - Consult memory at the start of every new chat/session, recall relevant project context, and automatically save reusable decisions and patterns after significant work. Prefer the available memory tool/MCP and use CLI fallback when needed. | Knowledge persistence | Session start and after significant work |
+| `systematic-debugging` | Structured bug isolation and root-cause resolution. | Debugging | When bugs appear |
+| `documentation` | Generate technical docs, architecture notes, and usage guidance. | Documentation | `openspec-verify-change` |
+| `sync-index` | Keep project index and generated guidance synchronized with implementation. | Documentation sync | `openspec-apply-change` |
+| `changelog-generator` | Create user-facing release notes from implementation changes. | Release communication | `openspec-archive-change` |
+
+---
 
-### Persistent Memory Protocol (Mandatory)
+## Persistent Memory Protocol (Mandatory)
 
 The AC Framework includes a persistent memory system that agents must use proactively.
 
 **Session-start requirement (always):**
-1. At the start of every new chat/session, consult the available persistent memory tool or MCP before planning, implementing, or giving project-specific guidance.
+1. At the start of every new chat/session, consult the available persistent memory tool or MCP before planning or implementing.
 2. Recall project-level context first, then search for task-specific decisions, conventions, bugfixes, and architecture notes.
-3. Treat recalled memory as active project context unless the current repository state or an explicit user instruction supersedes it.
-4. If memory tooling is unavailable, continue with repository inspection and use the AC Framework CLI fallback when possible.
-
-**What gets saved automatically:**
-- Architectural decisions from proposals/designs
-- Bugfix patterns and solutions
-- Performance optimizations
-- Refactoring techniques
-- Security fixes
-- API patterns and conventions
-- Reusable workflow conventions and project constraints
-
-**How to use memory:**
+3. Treat recalled memory as active project context unless current repository state or explicit user instruction supersedes it.
+4. If memory tooling is unavailable, continue with repository inspection and use AC Framework CLI fallback.
+
+**What gets saved automatically (only reusable context):**
+- Architectural decisions from proposal/design artifacts
+- Bugfix patterns and repeated solutions
+- Performance and optimization insights
+- Refactoring techniques and conventions
+- Reusable workflow constraints and team rules
+
+**Memory hygiene rules:**
+- Never save secrets, credentials, tokens, or sensitive one-off values
+- Redact content inside `<private>...</private>` before saving
+- Use concise titles, correct memory type, useful tags, realistic confidence
+
+**User communication:** `Memory saved: [brief description]`
+
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
 ```text
-Preferred: use the available persistent memory tool or MCP for recall, search, save, and project-scoped context.
-Fallback: use the AC Framework memory CLI commands when direct tool access is not available.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Recall relevant context before starting work
-acfm memory recall "implementing authentication"
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
 
-# Search for specific patterns
-acfm memory search "JWT token refresh"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
 
-# Get full context for current project
-acfm memory recall
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
-# View statistics
-acfm memory stats
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
-**When the agent saves memory (automatic):**
-1. After completing proposal.md (saves architectural decisions)
-2. After fixing bugs (solutions are stored)
-3. After refactoring (techniques are recorded)
-4. After optimizations (performance insights)
-5. After any significant decision with confidence > 0.7
-6. After identifying conventions, constraints, or reusable operating rules worth preserving
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
 
-**Memory hygiene rules:**
-- Save only reusable information likely to matter in future chats.
-- Do not save secrets, credentials, tokens, or one-off sensitive data.
-- Redact content inside `<private>...</private>` before saving.
-- Prefer concise titles, the correct memory type, clear tags, and realistic confidence scores.
+## SynapseGrid Collaborative MCP Protocol (Optional)
 
-**User communication:** "Memory saved: [brief description]" when auto-saving occurs.
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
 
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
 
-### OpenSpec Skills (The heart of the framework)
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
 
-| Skill | Description | Primary Use | Required Before |
-|-------|-------------|-------------|-----------------|
-| `openspec-explore` | Exploration mode to investigate problems, map architecture, find integration points before implementing. | Pre-analysis | `acfm-spec-workflow` |
-| `openspec-new-change` | Creates a new change with step-by-step workflow (proposal → specs → design → tasks). | Structured start | `brainstorming` |
-| `openspec-ff-change` | Fast-forward: creates all artifacts at once to start implementation quickly. | Quick start | `brainstorming` |
-| `openspec-continue-change` | Continues an existing change by creating the next artifact in the sequence. | Continue workflow | `openspec-new-change` OR `microtask-decomposition` |
-| `openspec-apply-change` | Implements tasks from a change (applies code according to specs and tasks). | Change execution | `test-generator` |
-| `openspec-verify-change` | Verifies that implementation matches artifacts (specs, tasks, design). | Validation | `openspec-apply-change` |
-| `openspec-archive-change` | Archives a completed change by moving it to `{specDir}/changes/archive/`. | Change closure | `openspec-verify-change` |
-| `openspec-onboard` | Guided tutorial to learn OpenSpec with a complete example workflow. | Learning | `acfm-spec-workflow` |
-| `openspec-sync-specs` | Synchronizes delta specs to main specs (intelligent merge). | Update specs | `openspec-verify-change` |
-| `openspec-bulk-archive-change` | Archives multiple completed changes at once. | Bulk cleanup | `openspec-verify-change` |
-
-### Documentation and Debugging Skills
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
 
-| Skill | Description | Primary Use | Required Before |
-|-------|-------------|-------------|-----------------|
-| `project-index` | Generates structured project documentation: structure analysis, domains, agent guides. | Indexing and context | `project-constitution` |
-| `sync-index` | Keep project documentation (`project-index` and sub-skills) in sync with codebase changes. | Documentation Sync | `openspec-apply-change` |
-| `systematic-debugging` | Structured debugging in 4 phases: root cause investigation, pattern analysis, hypothesis, implementation. | Problem resolution | When bugs found |
-| `changelog-generator` | Creates automated changelogs from git commits, translating technical to user language. | Version history | `openspec-archive-change` |
-| `skill-writer` | Guide to create new skills for Claude Code with correct structure and frontmatter. | Create new skills | Anytime |
-| `vercel-react-best-practices` | React and Next.js performance optimization guidelines from Vercel Engineering. | React/Next.js optimization | [IF REACT] |
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
-### AC Framework Enhancement Skills
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
 
-| Skill | Description | Primary Use | Required Before |
-|-------|-------------|-------------|-----------------|
-| `microtask-decomposition` | **LEVEL 2+ DECOMPOSITION** - Use when a single task from tasks.md is still too complex (affects 3+ files or requires multiple logic blocks). Breaks tasks into MICROTASKS (1 file/function each) for granular implementation. NOT for initial task breakdown. | Microtask planning & delegation | `openspec-continue-change` |
-| `testing-qa` | Automate generation and maintenance of unit, integration, and E2E tests; generate test data and debugging. | Quality assurance | `openspec-apply-change` |
-| `code-review` | Review generated code for style, security, and architecture issues; suggest refactorings and performance improvements. | Code quality & security | `openspec-apply-change` |
-| `documentation` | Generate clear documentation for each task: technical descriptions, architecture diagrams, usage guides. | Documentation & communication | `openspec-verify-change` |
-| `research-retrieval` | Search external documentation (web pages, API docs, papers) and generate useful summaries for development. | Research & context gathering | `openspec-explore` |
-| `context-synthesizer` | Manage memory in long projects and summarize current state to prevent agent context loss. | Memory & context management | `project-constitution` |
-| `ci-deploy` | Automate continuous integration, deployment, and post-deployment verification of developed solutions. | CI/CD automation | `openspec-verify-change` |
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
 
 ---
 
@@ -146,363 +182,196 @@ acfm memory stats
 **Rule 1: Phase Completion Checkpoint**
 After EACH phase, you MUST confirm completion:
 ```
-╔══════════════════════════════════════════════════════════╗
-║    PHASE [X] COMPLETION CHECKPOINT                      ║
-╠══════════════════════════════════════════════════════════╣
-║  Have you COMPLETED ALL skills in Phase [X]?              ║
-║  [ ] Yes - I have read and executed every skill           ║
-║  [ ] No - I need to go back                               ║
-╚══════════════════════════════════════════════════════════╝
++------------------------------------------------------------+
+| PHASE [X] COMPLETION CHECKPOINT                            |
++------------------------------------------------------------+
+| Have you COMPLETED ALL skills in Phase [X]?                |
+| [ ] Yes - I read and executed every required skill         |
+| [ ] No  - I must go back and complete missing skills       |
++------------------------------------------------------------+
 ```
 **IF NO: STOP. Go back and complete missing skills.**
 
 **Rule 2: Skill Dependency Chain**
-Each skill table above shows "Required Before". You CANNOT use a skill until its dependency is satisfied.
+Each skill table above shows `Required Before`. You CANNOT use a skill before satisfying its dependency.
 
 **Rule 3: Output Verification**
-Before proceeding to next phase, verify you have these outputs:
+Before proceeding to next phase, verify outputs exist:
 
 | Phase | Required Outputs | Check |
-|-------|-----------------|-------|
-| Phase 0 | `acfm spec status` shows initialized and session memory recall completed | [ ] |
-| Phase 1 | project-constitution.md defined | [ ] |
-| Phase 2 | project-index.md exists, exploration notes | [ ] |
-| Phase 3 | proposal.md, specs/, design.md, tasks.md | [ ] |
-| Phase 4 | Tests written, code implemented, tasks marked complete | [ ] |
-| Phase 5 | Verification passed, docs updated, change archived | [ ] |
+|-------|------------------|-------|
+| Phase 0 | `acfm spec status` validated + memory recall completed | [ ] |
+| Phase 1 | `project-constitution` defined + mobile baseline declared | [ ] |
+| Phase 2 | exploration notes + platform/stack decision recorded | [ ] |
+| Phase 3 | `proposal.md`, `specs/`, `design.md`, `tasks.md` + `spec-analysis` review | [ ] |
+| Phase 4 | implementation done + tasks updated + issues debugged | [ ] |
+| Phase 5 | verification passed + docs/index synced + archive/sync complete | [ ] |
 
 **Rule 4: Pre-Implementation Safety Check**
 Before `openspec-apply-change`, ALL must be TRUE:
-- [ ] tasks.md exists and has checkboxes
-- [ ] All tests from `test-generator` are written
-- [ ] design.md has been reviewed
-- [ ] spec-analysis shows consistency
+- [ ] `tasks.md` exists and contains actionable checkboxes
+- [ ] Target platform(s) and stack (Flutter / React Native / Native iOS) are explicit
+- [ ] Required mobile skills for selected stack/platform have been applied
+- [ ] `design.md` and `spec-analysis` were reviewed
 
 **IF ANY IS FALSE: STOP. Complete missing items.**
 
 ---
 
-## Workflow: New Project
+## Workflow: New Mobile Project
 
-When starting a project **from scratch**, follow this **MANDATORY** workflow:
+When starting a mobile project **from scratch**, follow this **MANDATORY** workflow:
 
 ```
-┌─────────────────────────────────────────────────────────────────────────────────┐
-│                      WORKFLOW: NEW PROJECT - ZERO SKIP                      │
-└─────────────────────────────────────────────────────────────────────────────────┘
-
-    ┌─────────────────┐
-    │     START       │
-    └────────┬────────┘
-             │
-             ▼
-    ╔══════════════════════════════════════════════╗
-    ║    PHASE 0: AC FRAMEWORK SETUP (REQUIRED)   ║
-    ║  BLOCKING: Cannot proceed without this       ║
-    ╠══════════════════════════════════════════════╣
-    ║  1. acfm-spec-workflow                       ║
-    ║     └─ **ALWAYS START HERE**                 ║
-    ║     └─ Understand .acfm/ vs openspec/        ║
-    ║     └─ Learn CLI commands and workflow       ║
-    ║     └─ Check project initialization status   ║
-    ║     └─ RUN: acfm spec init (if needed)       ║
-    ║  2. acfm-memory                              ║
-    ║     └─ Recall memory at chat start           ║
-    ║     └─ Load prior decisions and conventions  ║
-    ╚════════════════════╬═════════════════════════╝
-                         ║
-                         ║  CHECKPOINT: Phase 0 Complete?
-                         ║    [ ] acfm spec status shows "initialized": true
-                         ║
-                         ║ YES ▼
-                         ▼
-    ╔══════════════════════════════════════════════╗
-    ║  PHASE 1: FOUNDATIONS & GOVERNANCE           ║
-    ╠══════════════════════════════════════════════╣
-    ║  1. project-constitution                     ║
-    ║     └─ Define core principles                ║
-    ║  2. secure-coding-cybersecurity              ║
-    ║     └─ Establish security guidelines         ║
-    ║  3. code-maintainability                     ║
-    ║     └─ Define quality standards              ║
-    ║  4. vercel-react-best-practices [IF REACT]   ║
-    ║     └─ Apply React/Next.js best practices    ║
-    ╚════════════════════╬═════════════════════════╝
-                         ║
-                         ║  CHECKPOINT: Phase 1 Complete?
-                         ║    [ ] project-constitution defined
-                         ║    [ ] Security guidelines established
-                         ║    [ ] Quality standards set
-                         ║
-                         ║ YES ▼
-                         ▼
-    ╔══════════════════════════════════════════════╗
-    ║  PHASE 2: CONTEXT & DISCOVERY                ║
-    ╠══════════════════════════════════════════════╣
-    ║  5. context-synthesizer                      ║
-    ║     └─ Initialize memory and context state   ║
-    ║  6. project-index                            ║
-    ║     └─ Document initial structure            ║
-    ║  7. research-retrieval                       ║
-    ║     └─ Gather external documentation         ║
-    ║  8. openspec-explore                         ║
-    ║     └─ Explore target architecture           ║
-    ║  9. brainstorming                            ║
-    ║     └─ Generate ALL questions in ONE prompt  ║
-    ║     └─ Surface hidden assumptions            ║
-    ║     └─ Challenge constraints                 ║
-    ╚════════════════════╬═════════════════════════╝
-                         ║
-                         ║  CHECKPOINT: Phase 2 Complete?
-                         ║    [ ] project-index.md exists
-                         ║    [ ] Exploration notes documented
-                         ║    [ ] Brainstorming questions answered
-                         ║
-                         ║ YES ▼
-                         ▼
-    ╔══════════════════════════════════════════════╗
-    ║  PHASE 3: REQUIREMENTS & DESIGN              ║
-    ╠══════════════════════════════════════════════╣
-    ║  10. spec-clarification (CRITICAL)           ║
-    ║      └─ CLARIFY requirements first           ║
-    ║  11. openspec-new-change                     ║
-    ║      └─ Create proposal                      ║
-    ║  12. microtask-decomposition                 ║
-    ║      └─ ONLY if task is still too complex    ║
-    ║      └─ Break into MICROTASKS (1 file each)  ║
-    ║  13. openspec-continue-change                ║
-    ║      └─ Draft Specs, Design, Tasks           ║
-    ║  14. spec-analysis                           ║
-    ║      └─ Verify consistency                   ║
-    ║  15. requirement-checklist                   ║
-    ║      └─ "Unit test" the specs                ║
-    ║  16. api-design-principles [IF APIs]         ║
-    ║      └─ Design REST/GraphQL APIs             ║
-    ║  17. interface-design [IF UI]                ║
-    ║      └─ Design dashboards/apps interface     ║
-    ╚════════════════════╬═════════════════════════╝
-                         ║
-                         ║  CHECKPOINT: Phase 3 Complete?
-                         ║    [ ] proposal.md created
-                         ║    [ ] specs/ directory with specs
-                         ║    [ ] design.md written
-                         ║    [ ] tasks.md with checkboxes
-                         ║    [ ] spec-analysis passed
-                         ║
-                         ║ YES ▼
-                         ▼
-    ╔══════════════════════════════════════════════╗
-    ║  PHASE 4: IMPLEMENTATION                     ║
-    ╠══════════════════════════════════════════════╣
-    ║    SAFETY CHECK - ALL MUST BE TRUE:        ║
-    ║  [ ] tasks.md exists                         ║
-    ║  [ ] Tests from test-generator written       ║
-    ║  [ ] design.md reviewed                      ║
-    ║  [ ] spec-analysis shows consistency         ║
-    ╠══════════════════════════════════════════════╣
-    ║  18. test-generator                          ║
-    ║      └─ TDD: Write tests first               ║
-    ║  19. openspec-apply-change                   ║
-    ║      └─ Implement code to pass tests         ║
-    ║  20. testing-qa                              ║
-    ║      └─ Automate test maintenance            ║
-    ║  21. code-review                             ║
-    ║      └─ Review for style/security/arch       ║
-    ║  22. secure-coding-cybersecurity             ║
-    ║      └─ Audit code for security              ║
-    ║  23. error-handling-patterns                 ║
-    ║      └─ Verify robust error handling         ║
-    ║  24. performance-optimizer                   ║
-    ║      └─ Optimize critical paths              ║
-    ╚════════════════════╬═════════════════════════╝
-                         ║
-                         ║  CHECKPOINT: Phase 4 Complete?
-                         ║    [ ] All tasks in tasks.md marked [x]
-                         ║    [ ] Tests passing
-                         ║    [ ] Code reviewed
-                         ║    [ ] Security audited
-                         ║
-                         ║ YES ▼
-                         ▼
-    ╔══════════════════════════════════════════════╗
-    ║  PHASE 5: VALIDATION & CLOSURE               ║
-    ╠══════════════════════════════════════════════╣
-    ║  25. systematic-debugging                    ║
-    ║      └─ Resolve any issues                   ║
-    ║  26. openspec-verify-change                  ║
-    ║      └─ Validate against specs               ║
-    ║  27. documentation                           ║
-    ║      └─ Generate technical docs & diagrams   ║
-    ║  28. sync-index                              ║
-    ║      └─ Update project documentation         ║
-    ║  29. changelog-generator                     ║
-    ║      └─ Generate release notes               ║
-    ║  30. ci-deploy                               ║
-    ║      └─ Deploy and verify solution           ║
-    ║  31. openspec-archive-change                 ║
-    ║      └─ Archive the change                   ║
-    ╚══════════════════════════════════════════════╝
++--------------------------------------------------------------------------+
+| WORKFLOW: NEW MOBILE PROJECT - ZERO SKIP                                 |
++--------------------------------------------------------------------------+
+
+  START
+    |
+    v
+  PHASE 0 - AC FRAMEWORK SETUP (BLOCKING)
+    1) acfm-spec-workflow
+       - verify initialization and workflow mode
+       - run `acfm spec init` if missing
+    2) acfm-memory
+       - perform session-start memory recall
+
+    CHECKPOINT: initialized + memory recall complete
+    |
+    v
+  PHASE 1 - FOUNDATIONS AND MOBILE BASELINE
+    3) project-constitution
+    4) mobile-design (mandatory baseline doctrine)
+    5) context-synthesizer
+    6) project-index (if not created)
+
+    CHECKPOINT: constitution + baseline mobile rules documented
+    |
+    v
+  PHASE 2 - DISCOVERY AND REQUIREMENTS
+    7) openspec-explore
+    8) research-retrieval
+    9) brainstorming (single comprehensive question set)
+    10) openspec-new-change (or openspec-ff-change if explicitly chosen)
+    11) spec-clarification
+
+    CHECKPOINT: scope clarified + platform/stack chosen
+    |
+    v
+  PHASE 3 - DESIGN AND TASK PLANNING
+    12) openspec-continue-change (proposal/specs/design/tasks)
+    13) spec-analysis
+    14) microtask-decomposition [IF tasks are still too complex]
+    15) platform/stack skills as required:
+        - mobile-ios-design [IF iOS UI]
+        - mobile-android-design [IF Android UI]
+        - react-native-design [IF RN UI]
+        - react-native-architecture [IF RN architecture]
+        - react-state-management [IF complex state]
+        - flutter-expert [IF Flutter]
+        - ios-developer [IF native iOS]
+
+    CHECKPOINT: proposal/spec/design/tasks coherent and implementation-ready
+    |
+    v
+  PHASE 4 - IMPLEMENTATION
+    16) openspec-apply-change
+    17) systematic-debugging [IF issues/regressions appear]
+    18) update tasks progress in tasks.md continuously
+
+    CHECKPOINT: implementation complete and stable
+    |
+    v
+  PHASE 5 - VALIDATION AND CLOSURE
+    19) openspec-verify-change
+    20) documentation
+    21) sync-index
+    22) openspec-sync-specs [IF syncing specs without archive]
+    23) openspec-archive-change OR openspec-bulk-archive-change
+    24) changelog-generator
 ```
 
-**Conditional Skills Notes:**
-- `[IF REACT]`: Use vercel-react-best-practices only if the project uses React or Next.js
-- `[IF APIs]`: Use api-design-principles only if the project involves REST/GraphQL APIs
-- `[IF UI]`: Use interface-design only if the project has dashboards, admin panels, or apps
-- `microtask-decomposition`: Use ONLY when a single task from tasks.md is still too complex (3+ files). NOT for initial breakdown.
+**Conditional Skill Notes:**
+- Use only skills that match selected platform/stack and risk profile.
+- `mobile-design` is mandatory for all mobile work regardless of stack.
+- `microtask-decomposition` is only for complex tasks after tasks.md exists.
 
 ---
 
-## Workflow: Existing Project
+## Workflow: Existing Mobile Project
 
-When working on an **existing codebase** (adding features, fixing bugs, refactoring):
+When working on an **existing mobile codebase** (feature, bugfix, refactor):
 
 ```
-┌─────────────────────────────────────────────────────────────────────────────────┐
-│                    WORKFLOW: EXISTING PROJECT - ZERO SKIP                    │
-└─────────────────────────────────────────────────────────────────────────────────┘
-
-    ┌─────────────────┐
-    │  START CHANGE   │
-    └────────┬────────┘
-             │
-             ▼
-    ╔══════════════════════════════════════════════╗
-    ║    PHASE 0: AC FRAMEWORK SETUP (REQUIRED)   ║
-    ║  BLOCKING: Cannot proceed without this       ║
-    ╠══════════════════════════════════════════════╣
-    ║  1. acfm-spec-workflow                       ║
-    ║     └─ **ALWAYS START HERE**                 ║
-    ║     └─ Verify project initialization         ║
-    ║     └─ Check existing changes                ║
-    ║  2. acfm-memory                              ║
-    ║     └─ Recall memory at chat start           ║
-    ║     └─ Load prior decisions and conventions  ║
-    ╚════════════════════╬═════════════════════════╝
-                         ║
-                         ║  CHECKPOINT: Phase 0 Complete?
-                         ║
-                         ║ YES ▼
-                         ▼
-    ╔══════════════════════════════════════════════╗
-    ║  PHASE 1: CONTEXT & ANALYSIS                 ║
-    ╠══════════════════════════════════════════════╣
-    ║  2. context-synthesizer                      ║
-    ║     └─ Load memory and context state         ║
-    ║  3. project-index (if needed)                ║
-    ║     └─ Map current system                    ║
-    ║  4. research-retrieval                       ║
-    ║     └─ Gather external documentation         ║
-    ║  5. openspec-explore                         ║
-    ║     └─ Deep dive into relevant modules       ║
-    ║  6. brainstorming                            ║
-    ║     └─ ALL questions in ONE prompt           ║
-    ║     └─ Ideate on feature/fix                 ║
-    ╚════════════════════╬═════════════════════════╝
-                         ║  CHECKPOINT
-                         ▼
-    ╔══════════════════════════════════════════════╗
-    ║  PHASE 2: DISCOVERY & CLARIFICATION          ║
-    ╠══════════════════════════════════════════════╣
-    ║  7. spec-clarification (CRITICAL)            ║
-    ║     └─ CLARIFY requirements first            ║
-    ║  8. openspec-new-change                      ║
-    ║     └─ Initialize change artifact            ║
-    ║  9. microtask-decomposition                  ║
-    ║     └─ If task too complex                   ║
-    ╚════════════════════╬═════════════════════════╝
-                         ║  CHECKPOINT
-                         ▼
-    ╔══════════════════════════════════════════════╗
-    ║  PHASE 3: DESIGN & PLANNING                  ║
-    ╠══════════════════════════════════════════════╣
-    ║  10. openspec-continue-change                ║
-    ║      └─ Draft Specs, Design, Tasks           ║
-    ║  11. spec-analysis                           ║
-    ║      └─ Check consistency with existing      ║
-    ║  12. requirement-checklist                   ║
-    ║      └─ Validate requirements                ║
-    ║  13. api-design-principles [IF APIs]         ║
-    ║      └─ Design API changes                   ║
-    ║  14. interface-design [IF UI]                ║
-    ║      └─ Design interface changes             ║
-    ╚════════════════════╬═════════════════════════╝
-                         ║  CHECKPOINT
-                         ▼
-    ╔══════════════════════════════════════════════╗
-    ║  PHASE 4: IMPLEMENTATION                     ║
-    ╠══════════════════════════════════════════════╣
-    ║    SAFETY CHECK REQUIRED                   ║
-    ╠══════════════════════════════════════════════╣
-    ║  15. test-generator                          ║
-    ║      └─ Generate tests for new feature       ║
-    ║  16. openspec-apply-change                   ║
-    ║      └─ Implement code                       ║
-    ║  17. testing-qa                              ║
-    ║      └─ Automate test maintenance            ║
-    ║  18. code-review                             ║
-    ║      └─ Review for style/security/arch       ║
-    ║  19. secure-coding-cybersecurity             ║
-    ║      └─ Audit new code                       ║
-    ║  20. error-handling-patterns                 ║
-    ║      └─ Verify error handling                ║
-    ║  21. performance-optimizer                   ║
-    ║      └─ Ensure no perf degradation           ║
-    ╚════════════════════╬═════════════════════════╝
-                         ║  CHECKPOINT
-                         ▼
-    ╔══════════════════════════════════════════════╗
-    ║  PHASE 5: OPTIMIZATION & VERIFICATION        ║
-    ╠══════════════════════════════════════════════╣
-    ║  22. systematic-debugging                    ║
-    ║      └─ Fix regressions                      ║
-    ║  23. openspec-verify-change                  ║
-    ║      └─ Final verification                   ║
-    ║  24. documentation                           ║
-    ║      └─ Generate technical docs & diagrams   ║
-    ║  25. sync-index (IMPORTANT)                  ║
-    ║      └─ Update docs with new changes         ║
-    ║  26. changelog-generator                     ║
-    ║      └─ Generate release notes               ║
-    ║  27. ci-deploy                               ║
-    ║      └─ Deploy and verify solution           ║
-    ║  28. openspec-archive-change                 ║
-    ║      └─ Archive change                       ║
-    ╚══════════════════════════════════════════════╝
++--------------------------------------------------------------------------+
+| WORKFLOW: EXISTING MOBILE PROJECT - ZERO SKIP                            |
++--------------------------------------------------------------------------+
+
+  START CHANGE
+    |
+    v
+  PHASE 0 - SETUP (BLOCKING)
+    1) acfm-spec-workflow (status, current changes, initialization)
+    2) acfm-memory (session-start recall)
+
+  PHASE 1 - CONTEXT AND DISCOVERY
+    3) context-synthesizer
+    4) project-index [if missing/stale]
+    5) openspec-explore
+    6) research-retrieval
+    7) brainstorming
+
+  PHASE 2 - CLARIFICATION AND CHANGE INIT
+    8) openspec-new-change
+    9) spec-clarification
+
+  PHASE 3 - DESIGN, CONSISTENCY, AND PLATFORM FIT
+    10) openspec-continue-change
+    11) spec-analysis
+    12) microtask-decomposition [if needed]
+    13) apply required mobile platform/stack skills
+
+  PHASE 4 - IMPLEMENTATION
+    14) openspec-apply-change
+    15) systematic-debugging [if needed]
+
+  PHASE 5 - VALIDATION AND CLOSURE
+    16) openspec-verify-change
+    17) documentation
+    18) sync-index
+    19) openspec-sync-specs [if needed]
+    20) openspec-archive-change / openspec-bulk-archive-change
+    21) changelog-generator
 ```
 
-**Conditional Skills Notes:**
-- `[IF APIs]`: Use api-design-principles only if modifying/creating REST/GraphQL APIs
-- `[IF UI]`: Use interface-design only if modifying dashboards, admin panels, or apps
-- `project-index`: Run only if you haven't indexed the project yet or need to refresh context
-
 ---
 
 ## Skill Loading Reference
 
 All skills are located in: `skills/`
 
-To load a skill, read its SKILL.md file:
-- Example: Read `skills/spec-clarification/SKILL.md` to use the clarification workflow
-- Example: Read `skills/interface-design/SKILL.md` to use interface design principles
+To load a skill, read its `SKILL.md` file:
+- Example: `skills/spec-clarification/SKILL.md`
+- Example: `skills/mobile-design/SKILL.md`
+- Example: `skills/react-native-architecture/SKILL.md`
 
 ### MANDATORY SKILL EXECUTION CHECKLIST
 
-Before claiming a skill is "done", verify:
-- [ ] I have read the entire SKILL.md file
-- [ ] I have executed ALL steps in the skill
-- [ ] I have the required output artifacts
-- [ ] I can answer: "What did this skill produce?"
-
-**Remember**: Skills are documentation-based workflows with ZERO SKIP policy. Load them by reading the SKILL.md files, execute CLI commands when instructed, and NEVER proceed without completing all steps.
+Before claiming a skill is done, verify:
+- [ ] I read the entire `SKILL.md`
+- [ ] I executed all required steps
+- [ ] I produced required artifacts/checkpoints
+- [ ] I can explain exactly what the skill produced
 
 ---
 
 ## VIOLATION CONSEQUENCES
 
-If you SKIP a skill or phase:
-1. The framework integrity is compromised
-2. Quality cannot be guaranteed
-3. You MUST go back and complete what was skipped
-4. No exceptions. No shortcuts. Follow the workflow.
+If you skip a skill or phase:
+1. Workflow integrity is compromised
+2. Mobile quality and consistency are no longer guaranteed
+3. You MUST return and complete the missing steps
+4. No shortcuts. No exceptions.
 
 **Quality over speed. Documentation before code. Planning before execution.**