annotate-guidance

Annotate Guidance

You are tasked with generating architecture guidance files for a brownfield project. You will map the project structure, auto-detect its architecture, analyze each architectural layer, and batch-write compact architecture.md files under .rpiv/guidance/ mirroring the project's directory structure.

Input

$ARGUMENTS — optional target directory. Defaults to the current working directory.

Steps to follow:

1. Read any directly mentioned files first:

   • If the user mentions specific files (existing architecture.md, CLAUDE.md, architecture docs, READMEs), read them FULLY first
   • IMPORTANT: Use the Read tool WITHOUT limit/offset parameters to read entire files
   • CRITICAL: Read these files yourself in the main context before invoking any skills
   • This ensures you have full context before decomposing the work

2. Pass 1 — Map the project (parallel agents):

   • Spawn the following agents in parallel using the Agent tool:

   Agent A — Project tree mapping:

   • subagent_type: codebase-locator
   • Prompt: "Map the full project tree structure for {target directory}. List all directories and their contents, respecting .gitignore. Focus on source code directories, configuration files, and build artifacts. Return a complete tree view."

   Agent B — Architecture and conventions:

   • subagent_type: codebase-locator
   • Prompt: "Identify the architectural layout of {target directory} from path shape and manifest files — NO content analysis. Detect: (1) Architecture pattern inferred from folder shape — clean-arch via Domain/Application/Infrastructure dirs; MVC via Controllers/Models/Views; monorepo via packages/* + workspaces; microservices via services/* with individual manifests; hexagonal via ports/adapters. (2) Main layers/modules — top-level source directories + their names. (3) Frameworks and languages from manifest files (package.json dependencies, *.csproj TargetFramework, pyproject.toml, go.mod, Cargo.toml) and file extensions. (4) Build system from build-config filenames (vite/webpack/tsup/esbuild configs, Makefile, nx.json, turbo.json, dotnet .sln). For each main layer/module, check sub-directory composition. If sub-directories with distinct names/roles exist, flag each as a guidance target candidate with: (a) path, (b) role inferred from folder name (controllers/, services/, entities/, components/, stores/, etc.), (c) file count via ls, (d) how its sub-directory composition differs from sibling layers. Use grep/find/ls only. Do not read file contents. Pass 2 runs codebase-analyzer + codebase-pattern-finder per target folder for deep analysis."