--- description: "Standalone feature-spec analysis. Two profiles picked at intake: global (23-section development handoff, evidence-trimmed) 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ı, kanıta göre budanır) 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: "[\"\" | check | refresh | conform ] [--no-cache] [--preview-conventions]" parameters: [{"name":"name","kind":"text"},{"name":"--no-cache","kind":"flag"},{"name":"--preview-conventions","kind":"flag"}] gui: form destructive: false confirm: none --- # multi-agent analysis - Feature Spec Analysis (v3) > **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text. > > **Background runs** (`MULTI_AGENT_UNATTENDED=1`, no `autopilot`): never ask or default a picker; write `agent-state.json`, park on the question, stop (`$HOME/.claude/multi-agent-refs/picker-contract.md`, Background). 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 feature-spec document - up to 23 sections, trimmed to whatever the evidence supports - 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.question`, `.options[].label` and `.options[].description` follow `outputLanguage`; only `header` stays English (<=12-char chip). The emitted analysis document body follows `outputLanguage` (`tr` or `en`). ## Gotchas - Design is fetched only inside this command (Locked 29). A variant missing from the document is added by re-running analysis, never by a later phase. - `status: final` fails the validator while any `AS-NN` is still open; publish drafts as `draft`. ## 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 37, 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. - `check ` / `refresh ` - not a name: compare the document with its sources, or redraft from the stale ones. Read `$HOME/.claude/multi-agent-refs/features/analysis-sources.md` and follow it instead of the steps below. - `conform ` - not a name: map an existing document onto a template without changing what it says. Follow `$HOME/.claude/multi-agent-refs/features/analysis-outline.md` instead of the steps below. ## Profile Phase 0 Step 1b asks which analysis standard the document follows (Locked 31), 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 32). | 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 34). 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`. The document 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: **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). Sections are chosen from evidence; there is no second mode (ADR-0015, `docs/adr/0015-one-pipeline-no-depth-answer.md` in the pipeline repo). Section omission rule (Locked 2): zero-evidence and default-drop sections omit entirely; a rendered section keeps its canonical template number, so the rendered set has gaps. 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 25); Pass B projects each concept onto the selected platform with a footnote per filled cell (Locked 24). ### Phases 3, 3.2, 3.3, 3.5, 4, 5 - Render, review, 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 33), 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 Full procedure: `$HOME/.claude/multi-agent-refs/analysis/resume.md`. Read it when `/multi-agent:resume` is invoked on an analysis run (`state.analysisSpec.phase` enumeration and the re-entry rule per paused phase; evidence and synthesis already in state are never re-fetched). ## Reusable refs Full table: `$HOME/.claude/multi-agent-refs/analysis/reusable-refs.md`. Read it when a phase needs a fetcher, extractor, dispatcher, validator or fallback ref and the phase ref does not name its path. ## Notes - 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 | web | backend` for a repo-backed run, or `mobile | web` for the channels a repo-less run derives from its evidence (Locked 34). `web` is the pre-`web` spelling and is still read back for older state and documents. 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 (the Standards question)**: When `evidence.standards[]` is non-empty, every decision in Section 13 (Architecture Plan, corporate Section 17) must cite the binding source in its 13.7 Standards-binding table. The renderer enforces this by failing render if any 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 (the Firebase question)**: Console URLs are never fetched (auth-gated). Only `:names` and `:schema` inputs feed `evidence.firebase[]`. Section 11 Analytics (corporate Section 13) 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. - **Standards vs Confluence vs Document split**: the Confluence question collects feature-specific spec pages and the Document question the same spec delivered as a `.docx` / `.pdf` / `.md` / `.txt` file - both describe what the feature IS and both land in `evidence.documents[]`. The Standards question collects cross-cutting documentation that constrains the development plan (architecture, coding conventions, navigation pattern). A source pasted in more than one of the three is de-duplicated (by URL, or by `realpath` for a local file) and the Standards entry wins, because it retains the binding flag. - **Workspace coding documentation default**: when the Standards question's 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**: the Standards and Firebase 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:Plan" "3:Review" "4:Commit" "5: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. Register one tile per phase of the active set (`0:Init 1:Plan 3:Review 4:Commit 5:Report`) with `TaskCreate`, persist each `taskId` via `phase-tracker.sh meta tasklist_id ""`, and at every phase entry, sub-step and exit pair a `TaskUpdate` (status or `activeForm`) with the matching `phase-tracker.sh update`. Call pattern: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "Call pattern". Mirror each with `phase-tracker.sh task` ("Mirroring the host's task list"). `analysis` mode does NOT TaskCreate phase 2: register tiles for the active set only. #### TaskCreate ordering (strict) **All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied**, and a later batch only ever appends phases numbered above everything already registered. For `analysis` that means: Phase 0 → Phase 1 → Phase 3 → Phase 4 → Phase 5. 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 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.