--- description: "Standalone feature-spec analysis. Two profiles picked at intake: global (23-section development handoff, 8 of them in Lite mode) or corporate (IG/UC/FG requirements document with traceability matrices). Platform-agnostic concept layer with repo-driven convention extraction (Phase 1c) and per-platform Pass B render; stack selection is optional. Collects Figma / Swagger / Confluence / Jira / Standards (Confluence + Wiki + local file) / Firebase / repo inputs. Stops after emit - does not chain into a dev run. Use when a feature needs a written specification before any code." description-tr: "Bağımsız özellik-spesifikasyonu analizi. Girişte iki profil: global (23 bölümlük geliştirme dokümanı, Lite modda 8'i) veya kurumsal (izlenebilirlik matrisleriyle IG/UC/FG gereksinim dokümanı). Repo'dan konvansiyon çıkarımıyla (Faz 1c) platform-bağımsız kavram katmanı ve platform başına Pass B render; stack seçimi opsiyonel. Figma / Swagger / Confluence / Jira / Standartlar (Confluence + Wiki + yerel dosya) / Firebase / repo girdilerini toplar. Çıktıyı üretince durur - dev koşusuna zincirlenmez." argument-hint: "[\"\"] [--lite | --full] [--no-cache] [--preview-conventions]" --- # multi-agent analysis - Feature Spec Analysis (v3) This command is **independent** from the orchestrator's Phase 1 analysis (which is a stack/findings detector inside `/multi-agent`). It produces a stakeholder-ready, platform-agnostic 23-section feature-spec document (or 7-section Lite mode) before any implementation starts. Each per-platform file is rendered by projecting concept-layer content onto repo-extracted conventions (Pass B). **Side-effect contract**: the command may write a local markdown file, post a Confluence page, or update a Jira description - but **never** creates branches, worktrees, commits, or PRs. It stops at the document. **Scope (development analysis, not a screen spec)**: this command produces a *development* analysis - what to build, the architecture plan, files to add, the test plan, and which existing components to reuse. It is NOT a design / screen-anatomy specification. The design itself is already produced elsewhere (figma-to-swiftui builds the components and binds them via Code Connect), so the analysis consumes those existing bindings as the source of truth for "what already exists" (see Phase 1b.1) instead of re-deriving the design. Do not grow this command toward exhaustive per-screen layout / gesture / state documentation; keep it development-focused. > **Language**: Per `$HOME/.claude/multi-agent-refs/rules.md` Language Application matrix - instruction prose stays English (this file is read as a system prompt). `AskUserQuestion.label` and `header` stay English. `question` and `description` follow `outputLanguage`. The emitted analysis document body follows `outputLanguage` (`tr` or `en`). ## Locked decisions (do not re-ask) These decisions are settled. Do not surface them as `AskUserQuestion` items, do not re-derive them from context, do not invite the user to override mid-run. If the user explicitly wants one of them changed, treat that as a separate request and update this list. The full list of 35, with the category index, lives in `$HOME/.claude/multi-agent-refs/analysis/locked.md`. Read it before the run starts; it is the contract the whole flow is judged against. `/multi-agent:analysis-resolve` inherits the same list. Cite a decision as `Locked ()` so the category is inferable. ## Input - `$ARGUMENTS` - optional analysis name (e.g. `"UserProfile"`). If empty, asked at Phase 0 Step 1. Stored internally as `state.analysisSpec.featureName` for backward compatibility. ## Profile Phase 0 Step 1b asks which analysis standard the document follows (Locked 32), and the answer selects the template. Both profiles read the same evidence: intake, fetching, repo evidence and convention extraction are shared, so the two cannot drift into two products. | Profile | Template | Shape | |---|---|---| | `global` (default) | `analysis-template.md` | Development handoff, 23 sections. Business rules with Gherkin acceptance criteria, architecture plan, files to add, test plan. Zero-evidence sections drop (Locked 2). | | `corporate` | `analysis-template-corporate.md` | Requirements document. `IG -> UC -> FG` spine with three traceability matrices, current and target state with impact analysis, then Technical Analysis and Development Analysis. The Part A backbone always renders, carrying `N/A` or `EKLENECEK` (Locked 33). | One run emits one profile. A missing input never blocks either profile: the gap is written as `EKLENECEK` and raised as a Section 20 open question rather than halting the run. **Stack is optional** (Locked 35). When no platform is selected the run still completes: everything that does not need a target repository renders in full, and only the development layer plus the Pass B projection are skipped, with a Section 20 row recording why. The output is a single file at `~/Desktop/multiAgentAnalysis//.md` instead of one per repo: without a repo there is no working tree for the usual `analysis/` path to be relative to, and the current working directory is never written to. The Phase 3.5 picker shows the resolved path and accepts an override. ## Template v3 template at `$HOME/.claude/multi-agent-refs/analysis-template.md`. Full mode renders up to 23 main sections + footer, minus any dropped by the omission table. The analysis doc is a development handoff, so low-signal sections are default-drop even in Full: **19 Alternatives** (render only for a real 2+-option architectural decision), **22 Glossary** (render only on request or >5 unfamiliar domain terms), and **18 Rollout** (compact checklist only, dropped when the pipeline's own commit/PR/rollout phase covers it). Lite mode renders 7 main sections (1 Summary, 2 Goals + Non-Goals, 4 User Stories, 9 API Contracts, 13 Architecture, 14 Files to Add, 21 References) plus optional 23 Changelog. Section omission rule (Locked 2): zero-evidence and default-drop sections omit entirely; numbering re-flows to stay sequential `1..N` over the rendered set. Numbering is plain Arabic numerals: `## 1. Geliştirme Özeti` / `## 1. Summary`, `## 2. Hedefler ve Karşı Hedefler` / `## 2. Goals and Non-Goals`. No special section characters; the section sign codepoint (U+00A7) is banned by `feedback_no-section-sign`. The template is platform-agnostic (Locked 22). It speaks in concepts (state holder, view, navigator, use case, repository, DTO, state model, DI register, localization key, accessibility identifier, test method). Pass B (Phase 2b) projects each concept onto the selected platform using `state.analysisSpec.evidence.conventions[]` extracted at Phase 1c. Every projected cell carries a footnote pointing to its evidence source (Locked 24). ## Steps ### Phase 0 - Intake Full picker chain: `$HOME/.claude/multi-agent-refs/analysis/intake.md`. Sequential `AskUserQuestion` steps filling `state.analysisSpec.*`: analysis name, analysis profile, account, platform multi-select, repos per platform, the six-question source batch (Figma / Swagger / Confluence / Jira / Standards / Firebase) and the two coverage opt-ins. Step narration is required - the chain length is known up front, so every step prints its breadcrumb. ### Phases 1, 1b, 1b.1, 1c - Evidence gathering Full contract: `$HOME/.claude/multi-agent-refs/analysis/evidence.md`. Fetches every declared source in parallel (Figma / Swagger / Confluence / Jira / Standards / Firebase), collects the 13-bucket repo evidence, builds the Code Connect index, and extracts the seven convention groups. Output: `state.analysisSpec.evidence.*`. Nothing here writes a document. ### Phase 2, 2a, 2b - Two-pass synthesis Full contract: `$HOME/.claude/multi-agent-refs/analysis/synthesis.md`. Pass A builds the platform-agnostic concept layer; Phase 2a previews the resolved conventions for approval (Locked 26); Pass B projects each concept onto the selected platform with a footnote per filled cell (Locked 24). ### Phases 3, 3.5, 4, 5 - Render, publish, report Full contract: `$HOME/.claude/multi-agent-refs/analysis/render.md`. Renders one markdown file per platform, runs the **required** `ai-common-toolkit:humanizer` pass, gates on `validate-analysis-doc.mjs` and on the `build-references.mjs --check` references coverage gate (Locked 34), asks for the output destination, dispatches to Local / Confluence / Jira (a Jira issue receives a comment unless the user explicitly asks for the description, which is never overwritten without a backup and a confirmation), then reports and stops. The humanizer pass and the validator are required in every mode; a document that skipped either is not shippable. ### Resume contract `state.analysisSpec.phase` enumeration: - `intake` (Phase 0 in progress) - `fetching` (Phase 1 in progress) - `collecting_repo_evidence` (Phase 1b) - `extracting_conventions` (Phase 1c) - `synthesizing_pass_a` (Phase 2 Pass A) - `awaiting_pass_b_approval` (Phase 2a - preview not yet answered) - `rendering_pass_b` (Phase 2b) - `drafting` (Phase 3) - `awaiting_output_decision` (Phase 3.5 - drafts written, picker not yet answered) - `dispatching` (Phase 4) - `reporting` (Phase 5) - `done` - `cancelled_at_pass_b_preview` (user cancelled at Phase 2a) When `/multi-agent:resume` is invoked and `phase == "awaiting_output_decision"`: 1. Check `state.analysisSpec.outputs.draftDir` exists on disk and contains the expected per-platform `.md` files. 2. If present, jump directly to Phase 3.5 (re-prompt the output picker; do not re-fetch evidence, do not re-synthesize). 3. If missing, print `WARN: scratch drafts at are gone; re-running Phase 2 synthesis from fetched evidence.` and restart from Phase 2 (cheap: evidence is still in state). When `phase == "awaiting_pass_b_approval"`: 1. Re-present the convention preview table (Phase 2a) with the same options. 2. Pass A synthesis results are kept in state; Phase 1b / 1c results are kept too. 3. Approval continues to Phase 2b without re-running anything. When `phase == "cancelled_at_pass_b_preview"`: 1. Print `state.analysisSpec.outputs.draftDir` (likely empty unless prior drafts exist from a previous run). 2. Show the convention preview that was rejected (for context). 3. Ask whether to restart from Phase 0, retry Phase 1c with fresh evidence, or abort. ## Reusable refs | Path | Reason | |------|--------| | `~/.claude/lib/submodule-detector.sh` | Phase 0 Step 4 repo discovery | | `~/.claude/lib/context-link-extractor.sh` | Phase 0 Step 5/Q6 URL classifier (handles `local-file`, `wiki`, `standards-confluence`, `generic-doc`, `firebase-events:names`, `firebase-events:schema`, `firebase-events:console` types) | | `~/.claude/lib/fetch-swagger.sh`, `fetch-confluence.sh` | Phase 1 fetchers | | Phase 1 wiki fetch chain (inline, no standalone script) | `git clone --depth 1 .wiki.git` first, `gh api repos/.../contents/.md` second, WebFetch third - see the Phase 1 type table `wiki` row | | `~/.claude/lib/extract-conventions.sh` | Phase 1c convention extractor (7 pattern groups, JSON output, confidence levels) | | `~/.claude/lib/figma-screenshot.sh` | Phase 2b Tier 2 Figma image downloader (REST API, section drill, 2x scale PNG, manifest.json) | | `~/.claude/lib/md2confluence-v3.py` | Phase 4 Confluence dispatch (multipart attachments, `` injection, mermaid macro + fallback, tooltip footnote macro, punctuation gate) | | `ai-common-toolkit:humanizer` | Phase 3 tone pass | | 8-locale set (ar, de, en, es, fr, it, ru, tr) + localization-key naming (inline) | Section 10 localization generation | | `$HOME/.claude/multi-agent-refs/channels/confluence.md` | Phase 4 Confluence dispatch | | `$HOME/.claude/multi-agent-refs/channels/jira.md` | Phase 4 Jira dispatch | | `$HOME/.claude/rules/tdd.md` | Section 15 test naming | | `$HOME/.claude/multi-agent-refs/analysis-template.md` | Template master copy + language matrix (v3 - 23 sections) | | `$HOME/.claude/multi-agent-refs/conventions-defaults.md` | Pass B fallback defaults (4 platforms x 7 pattern groups) - applied when convention confidence is none AND standards binding is silent | | `$HOME/.claude/lib/jira-publish.sh` | Phase 4 Jira write: comment by default, description only on explicit choice - reads the current description first, backs it up, appends below a rule, refuses a non-empty replace without `--confirm-overwrite` | | `$HOME/.claude/scripts/validate-analysis-doc.mjs` | Phase 4 pre-dispatch gate: deterministic check of the emitted per-platform doc (front-matter, never-omitted sections, humanizer punctuation, Full-mode BR traceability) | | a project-supplied Confluence-embedded API-table parser (optional) | Parse endpoints from a Confluence page's Request Path / Service Name / Response Body table columns | | `~/-Standards.md` | Canonical home-dir standards reference (auto-detected at Q5 option 2; exact filename from `prefs.projects[].standardsFile`) | | `~/.claude/rules/*.md` | Fallback rules when `evidence.standards[]` is empty | ## Notes - Default `prefs.global.outputLanguage` is `tr` for this user. - The minimum possible output (per per-platform file) is `1. Scope` + `7. Development Plan` (both always-present). - If Confluence or Jira POST returns 401 / 403 during Phase 4, surface the error and offer Local fallback (the local drafts in `/tmp/` are still on disk; copying them into the repo working tree is always available). - The `analysis/` directory is not in `.gitignore`; the user can `git add analysis/` manually. No auto-commit. - **Per-platform file naming**: `analysis/-.md`. The `` slug is lowercase, one of `ios | android | backend | frontend`. The `` slug preserves the user's feature name with whitespace replaced by `-` (e.g. `User Profile` -> `UserProfile` or `Item-Status` depending on input shape; the renderer trims and de-duplicates dashes). - **Standards binding (Q5)**: When `evidence.standards[]` is non-empty, every decision in Section 7 must cite the binding source. The renderer enforces this by failing render if any Section 7 architectural decision has no `cite:` reference; the user is prompted to either tighten the source or add a Risk row acknowledging the missing citation. - **Firebase ingestion (Q6)**: Console URLs are never fetched (auth-gated). Only `:names` and `:schema` inputs feed `evidence.firebase[]`. Section 6 emits per-platform snippets but the events table itself is shared across all per-platform files (the rules / event vocabulary is one product invariant). - **Wiki access fallback chain**: Phase 1 `wiki` fetcher tries (a) `git clone .wiki.git`, (b) `gh api repos/.../contents/.md`, (c) raw `WebFetch` of the page URL. Only after all three fail does the entry land in `fetchErrors[]`. - **Local-file safety**: `local-file` reads are scoped to `~/`, `/Users/`, and the repo's working tree. Paths outside these prefixes are rejected with `WARN: refusing to read ; outside allowed roots` to avoid accidental ingestion of unrelated files. - **Q5 vs Q3 split**: Q3 (Confluence) collects feature-specific spec pages. Q5 (Standards) collects cross-cutting documentation that constrains the development plan (architecture, coding conventions, navigation pattern). A URL pasted in both questions is de-duplicated by URL and the Q5 entry wins (binding flag is retained). - **Workspace coding documentation default**: when Q5 option 2 (Auto-detect) is selected, the probe also reads `prefs.projects[].confluenceStandardsParent` (if set) and looks for child pages whose title starts with `Coding`, `Standards`, `Architecture`, or `Navigation`. If that fetch fails with auth, log a hint that the user should host an offline mirror at `prefs.projects[].standardsFile` (canonical local fallback). - **Mixed paste handling**: Q5 / Q6 Other inputs accept comma-separated mixed entries. Whitespace is trimmed; entries are de-duplicated by canonicalised string (lowercase scheme + host + path for URLs; `realpath` for local files; lowercase exact match for event names). - **Repo-evidence reuse policy**: Phase 1b's catalogue is consulted by Pass B Section 7 rendering. The `direct-match` tag is the strongest signal; a `same-domain` row becomes an advisory note ("consider adapting existing X in the same feature directory"); `cross-cutting` items become a sentence in the section preamble ("reuse the cross-feature X from Common/"). See Locked decision 11. ## Required: Phase Tracker Contract **The phase tracker is mandatory** - the agent cannot skip it. Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md). Two channels run in parallel at every phase boundary: 1. **State channel** (every CLI, identical): `phase-tracker.sh` writes to `tracker-state.json`. Drives `:resume`, `:log`, `:status`. 2. **Visual channel** (CLI-specific): native widget on Claude Code, ANSI render on every other CLI. Without it the user sees no phase progress. ```bash # Phase 0, very first shell call (every CLI): bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID" for p in "0:Init" "1:Analysis" "2:Planning" "4:Review" "6:Commit" "7:Report"; do bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}" done bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress # Every phase boundary (every CLI): bash $HOME/.claude/scripts/phase-tracker.sh update in_progress|completed|failed|skipped # After every LLM call (every CLI): bash $HOME/.claude/scripts/phase-tracker.sh tokens [cached] ``` ### Visual channel - Claude Code (native TaskList widget, required) In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack - this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints. **TaskCreate ordering (strict)**: All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number - out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN - register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)". ```text # Phase 0 startup - register one tile per phase (0..N), capture the taskId, persist it: for each phase in 0:Init, 1:Analysis, 2:Planning, 4:Review, 6:Commit, 7:Report: TaskCreate({ subject: "Phase : ", activeForm: "" }) -> returns taskId bash $HOME/.claude/scripts/phase-tracker.sh meta tasklist_id "" # Phase entry - flip the tile to in_progress alongside the state update: TaskUpdate({ taskId: , status: "in_progress" }) bash $HOME/.claude/scripts/phase-tracker.sh update in_progress # Active sub-step inside a phase - update activeForm so the spinner header reflects what's happening now: TaskUpdate({ taskId: , activeForm: "Editing TopBarView.swift" }) # Phase exit - flip to completed/failed/skipped on both channels: TaskUpdate({ taskId: , status: "completed" }) bash $HOME/.claude/scripts/phase-tracker.sh update completed ``` `analysis` mode does NOT TaskCreate phases 3/5 - those are not part of the `analysis` phase set (`0:Init 1:Analysis 2:Planning 4:Review 6:Commit 7:Report`). Only register tiles for the active set. #### TaskCreate ordering (strict) **All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `analysis` that means: Phase 0 → Phase 1 → Phase 2 → Phase 4 → Phase 6 → Phase 7. The native widget renders by creation order, not by phase number - out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)". ### Visual channel - Copilot CLI / plain shell These CLIs have no TaskList widget. After every state change the agent calls render, which prints a bordered ANSI card as the last tool result so the user sees an updated phase table: ```bash bash $HOME/.claude/scripts/phase-tracker.sh render ``` Do NOT call TaskCreate on these CLIs - the tool does not exist and the call fails.