---
allowed-tools: Task, Read, Write, TodoWrite
description: Run a full report of the project state including dependencies, architecture, components and etc.
required-agents: orchestrator, dependency-auditor, architectural-analyzer, component-deep-analyzer
---
# Project State Full Report

## Description

Produce a complete and auditable snapshot of the project by coordinating specialist agents and consolidating their outputs. Claude Code (YOU) acts as the coordinator. The orchestrator agent only prepares structure and later synthesizes outputs. The final deliverable is:

1. A README file named README-YYYY-MM-DD-HH:MM:SS.md with the CURRENT timestamp placed inside the orchestrator agent directory that contains a short project description and an index linking to every report produced by the agents

When creating the README index, list only the title for each report and link directly to the file using an absolute path that begins at the repository root with a single leading slash. Example link format: 

```
[Project Architecture](/<link-to-the-report>)
```

Validate every link before saving the README and ensure the path truly exists. Use the MANIFEST.md managed by the orchestrator agent as the source of truth to map all produced reports. It is INITIALIZED in Phase 1, UPDATED after each agent completes in Phases 2 and 3, and FINALIZED in Phase 4. Make sure to inform this behavior to the **orchestrator** Agent.

## Output template

Use the following template for the README file. Replace placeholders and remove any empty sections. Do not insert horizontal rules.

```
# <Project Name> Project State Full Report

<Short project description in one or two paragraphs>.
<Short description explaining about the goals of this document which is the consolidation of the main aspects of the project as whole, as an X-Ray.

Generated on: YYYY-MM-DD HH:MM:SS

## Overview and Architecture
<Project Overview>
<Project Architecture>

## Components
<Component Name>

## Dependencies
<Dependencies Report>
```

## Critical Constraints

1. NEVER hand the full workflow to the orchestrator agent
2. The orchestrator agent MUST execute ONLY two responsibilities. a) Phase 1 creates project structure according to the agent specification or explicit user flags such as --project-folder, --output-folder and --ignore-folders. b) Phase 4 synthesizes the outputs generated by other agents
3. Maintain STRICT agent separation a) Invoke each specialist agent in a separate Task call. b) The orchestrator agent must not spawn subagents. c) Claude Code (YOU) is the coordinator who sequences phases and parallel runs
4. FOLLOW EXACTLY the written specification of every agent stored under .claude/agents
5. NEVER write outputs outside the designated locations. NEVER create folders that are not explicitly defined by the orchestrator or the agent specifications
6. NEVER provide recommendations, action plans, code changes or upgrade instructions in the Project Overview. Summarize only what the agents reported
7. DO NOT estimate times or durations. AVOID vague language such as probably safe or should be fine
8. DO NOT fabricate CVEs or vulnerabilities. Use evidence produced by the dependency-auditor.

### MANDATORY AGENT SEPARATION

* Each agent MUST be invoked with a separate Task tool call
* The orchestrator MUST NOT be asked to spawn sub-agents itself
* YOU (Claude Code) are the coordinator, NOT the orchestrator agent
* All communication flows through YOU as the coordinator. YOU decide which new agents to start. After any agent finishes, YOU MUST trigger the orchestrator to update MANIFEST.md. In practice, this means calling Task(orchestrator) once per completed agent task so it can append the entry (title, absolute path rooted at /, agent, timestamp). Example: when Task(architectural-analyzer) completes, immediately invoke Task(orchestrator) to record the Architecture Report in MANIFEST.md.

## Execution Workflow

**Phase 1: Task(orchestrator)**

1. Read user flags and normalize paths. Respect --project-folder and --output-folder when provided. If not provided, use the default locations defined by the orchestrator specification
2. Create only the directories required by the orchestrator specification. Do not invent extra levels like output or reports unless the orchestrator specification itself requires them
3. Apply ignore list before any file reading. Never parse or scan files inside any folder listed in --ignore-folders
4. Initialize **MANIFEST.md** in the orchestrator directory with an empty index structure (title, absolute path, agent, timestamp).

**Phase 2: Task(dependency-auditor) and Task(architectural-analyzer) in parallel**

1. Task(dependency-auditor) produces a complete dependency report following its agent specification.
   Important: For dependency validation within this Task, use MCP servers such as Context7 and Firecrawl to verify versions, maintenance status, and known vulnerabilities.
2. Task(architectural-analyzer) produces a complete **Architecture Report** following its agent specification.
   Important: ONLY the orchestrator appends to **MANIFEST.md** when each Task completes.

**Phase 3: Task(component-deep-analyzer) in parallel, one per component**

1. Parse the **Architecture Report** from Phase 2, treating it as an artifact produced by the architectural-analyzer.

2. For each component listed in the **Architecture Report** (for example, in the "Critical Components Analysis" section or any section that enumerates components), launch a separate Task(component-deep-analyzer) for that component, in parallel.

3. Each Task(component-deep-analyzer) MUST fully analyze only its assigned component and produce an individual report.

4. Coverage requirement and example: if the **Architecture Report** lists 10 components, YOU MUST launch 10 parallel Task(component-deep-analyzer) executions and produce 10 corresponding component reports. No component may be skipped. 

5. After all Task(component-deep-analyzer) executions complete, YOU MUST verify that every component has a corresponding report. Reopen the **Architecture Report** and review its component sections line by line. If any component lacks a report, launch additional Task(component-deep-analyzer) executions for the missing components until coverage is 100%. 

IMPORTANT: Make sure to DO NOT duplicate any report, so, **ultrathink** if the report already exists before create a new one with a different or similar name, timestamp, etc. YOU MUST BE extremely precise with this verification.

**Phase 4: Task(orchestrator)**

1. Aggregate references to all generated reports
2. FINALIZE **MANIFEST.md** inside the orchestrator agent directory: validate all entries, ensure titles and absolute paths exist, de-duplicate, confirm agent names and timestamps.

**Phase 5: Task(YOU)**

1. Read MANIFEST.md from the orchestrator directory. Build the index using report titles and absolute links that start with a single slash
2. Validate each link before writing. Use the link validation algorithm defined below
3. Save README-YYYY-MM-DD-HH:MM:SS.md with the CURRENT date time inside the orchestrator directory

**REMEMBER:** The orchestrator agent is just another specialist that:

* Sets up project structure (Phase 1)
* Synthesizes outputs (Phase 4)
* It DOES NOT coordinate other agents - that's YOUR job (YOU, Claude Code)

## Usage Examples

Use `$ARGUMENTS` as the project folder and, if provided, the output files path and name.

NEVER use any other paths to save reports, files, or manifests unless they are explicitly provided by the user. Do not create subfolders such as `reports` or `output`.

NEVER create any files or folders that are not specified in the agent specification.&#x20;

FOLLOW EXACTLY the output pattern defined below.

```bash
# Run the workflow on the project based on the root folder
/run-project-state-full-report

# Run the workflow on the project folder provided by the user
/run-project-state-full-report --project-folder=project-folder

# Run the workflow and save the reports in the folder provided by the user. All reports, files and manifests have to be saved in the output folder using the following pattern: <output-folder>/<agent-name>/<file-name-provided-by-agent>.md. For example: output-folder/dependency-auditor/dependencies-report-YYYY-MM-DD-HH:MM:SS.md
/run-project-state-full-report --project-folder=project-folder --output-folder=output-folder

# Run the workflow and ignore the folders provided by the user. Do not read or audit the files in the folders provided by the user.
/run-project-state-full-report --ignore-folders=adk_repo,venv,.env,node_modules,.git
```

## Negative Instructions

1. NEVER modify or suggest edits to the codebase.
   * Examples: DO NOT open pull requests, rename files, refactor functions, change configuration defaults, or alter build scripts.
   * Allowed: Summarize findings only and reference the specific agent report where the issue is documented.

2. DO NOT run upgrades or prescribe migrations.
   * Forbidden examples: "npm update", "go get -u", "helm upgrade", "apply database migrations".
   * This command is descriptive, not prescriptive. Keep outputs informational.

3. DO NOT invent CVEs or assume vulnerabilities without explicit evidence from the dependency-auditor or MCP validation.
   * Forbidden: "probably vulnerable", "likely CVE-2023-XXXXX", or unverified security claims.
   * Allowed: Quote exact package names and versions and cite the findings produced by the dependency-auditor.

4. DO NOT use vague language.
   * Avoid phrases like "probably safe", "should be fine", "seems OK", "looks stable".
   * Use neutral, factual wording lifted from the agents' reports.

5. DO NOT use emojis or stylized characters.

6. DO NOT provide time estimates.
   * Forbidden: "in 2 hours", "by tomorrow", "within X days", or any duration claims.
   * If timing is requested, state that estimates are out of scope for this command.

7. NEVER create agent folders in the repository root.
   * Forbidden: "/agents", "/architectural-analyzer" at the repository root.
   * Allowed: Only use the paths specified by each agent or by the orchestrator, for example `docs/agents/orchestrator`.

8. NEVER create files or folders that are not specified by the agent or orchestrator specifications.
   * Forbidden: ad-hoc directories like "reports", "output", "tmp" unless they are explicitly defined.
   * All outputs must follow `<output-folder>/<agent-name>/<file-name-provided-by-agent>.md` or be stored in the orchestrator directory as specified.

8. NEVER duplicate a report. If you have to make any chances, edit the report that already exists instead of create a new one
    * Forbidden: duplicate a "component-analysis" report during the review if all reports exists.

## Observations

**Ultrathink** each step of the workflow and determine the clearest instructions for every agent so they can complete their tasks. As the coordinator/master (YOU), you MUST provide all necessary context to each agent. To do this, read every agent specification, understand step by step what each agent must do, and pass along the specific inputs, constraints, and paths they require to succeed.

The orchestrator alone maintains **MANIFEST.md**. Instruct the orchestrator to append a new entry to **MANIFEST.md** immediately after any agent finishes, recording the report title, the absolute path rooted at `/`, the agent name, and the timestamp.

Example: As soon as the **Architecture Report** is ready, the orchestrator MUST append its entry to **MANIFEST.md** and mark that task as completed.
