agentleFS
alex-voloshin-devalex-voloshin-dev/ai-skills/.agents/skills/project-init/SKILL.md

project-init

Skill2 starsChanged 6 months agoMITView on GitHub

Initialize AI context for an existing project — deep scan the codebase, detect tech stack, identify subprojects and major modules, generate root `AGENTS.md`, `ARCHITECTURE.md`, `TESTING.md`, and directory-scoped `AGENTS.md` files for subprojects and significant directories. Works with monorepos, polyglot projects, and large codebases via iterative scanning.

  • Reads credentials

43 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use harness-audit, workflow and 1 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • sattva2020Skill

    harness-audit

    Audits a codebase for "AI-agent harness" maturity across six layers (context engineering, tools & MCP, memory & state, tests & evals, observability, guardrails & approvals). Scores each layer, flags AGENTS.md/CLAUDE.md drift, gives prioritized fixes. Use for "audit harness", "оцени харнес", "check agent readiness", "is this project agent-ready", "проверь готовность к AI-агентам".

    Also in 3 projects that use this

  • VercelSkill

    workflow

    Creates durable, resumable workflows using Vercel's Workflow SDK. Use when building workflows that need to survive restarts, pause for external events, retry on failure, or coordinate multi-step operations over time. Triggers on mentions of "workflow", "durable functions", "resumable", "workflow sdk", "queue", "event", "push", "subscribe", or step-based orchestration.

    Also in 3 projects that use this

  • MicrosoftSkill

    handoff

    Compact the current conversation into a handoff document for another agent to pick up.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 10 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 22 edited versions we read keep these.

  • 10

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If files exist — read them, note gaps.

    line 67
  2. Distinctive:

    Import style and module organization

    line 82
  3. Very specific:

    Use the matching stack-specific template from .codex/templates/ as a starting point.

    line 109
  4. Distinctive:

    Keep concise — avoid repeating what scoped AGENTS.md files will cover

    line 118
  5. Very specific:

    Use templates/architecture.template.md as the starting point.

    line 124
  6. Distinctive:

    Document what exists now, not aspirations.

    line 128
  7. Very specific:

    Create TESTING.md at the project root using templates/testing.template.md (root template section).

    line 140
  8. Very specific:

    Key data sources: test config files → test types and commands.

    line 142
  9. Distinctive:

    Keep service-specific — do not repeat root TESTING.md content

    line 152
  10. Distinctive:

    After approval, create all files.

    line 223
  11. Distinctive:

    Verify it was created successfully

    line 225
  12. Distinctive:

    If updating existing files — show the diff and request confirmation.

    line 228
  13. Distinctive:

    After all files are created:

    line 232
  14. Distinctive:

    Precedes: All other workflows — run this first on a new project

    line 252

“Common” is measured: kept by at least 6 in 10 of the 22 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Project Init

Deep-scan an existing project and generate AI context files (AGENTS.md, ARCHITECTURE.md, TESTING.md) for the root and all significant subprojects. After completion, the runtime has the context it needs: tech stack, conventions, structure, setup, testing, security.

1. Initial Reconnaissance

1a. Root Structure Scan

// turbo
ls -la  # or Get-ChildItem on Windows

Identify stack signals:

SignalIndicates
package.json, tsconfig.jsonNode.js / TypeScript
pom.xml, build.gradleJava / Spring
pyproject.toml, requirements.txtPython
go.modGo
*.csproj, *.sln.NET
Cargo.tomlRust
Dockerfile, docker-compose.ymlContainerized
terraform/, *.tfInfrastructure as Code
helm/, k8s/, charts/Kubernetes
Multiple package.json / pom.xmlMonorepo
nx.json, turbo.json, pnpm-workspace.yaml, lerna.jsonMonorepo tooling
content/blog/, posts/, .mdx files with frontmatterBlog / file-based content
llms.txtAI search optimization

1b. Detect Project Boundaries

Identify project boundaries — directories that are independent units:

  • Monorepo: apps/, packages/, services/, libs/ with own config files
  • Single project: One root config, directories are modules (src/, app/, internal/)

Build a project map:

Project Root
├── [subproject-1] (type: service, stack: Java Spring Boot)
├── [subproject-2] (type: frontend, stack: Next.js + TypeScript)
├── [subproject-3] (type: infra, stack: Terraform)
└── [shared-lib]   (type: library, stack: TypeScript)

1c. Check for Existing Context Files

// turbo
find . -name "AGENTS.md" -o -name "ARCHITECTURE.md" -o -name "TESTING.md" -o -name "FEATURES.md" | head -20

If files exist — read them, note gaps. Create missing files, update outdated ones (with user confirmation).

2. Deep Scan — Iterative

Process one boundary at a time. Scan limits: max 10 boundaries, 20 files per boundary, 3 levels deep. For 100+ file boundaries, summarize from directory listing and configs only.

2a. Per-Boundary Scan Sequence

For each subproject or the root project:

  1. Config files first — package.json, pom.xml, pyproject.toml, go.mod, *.csproj, tsconfig.json, .eslintrc, Dockerfile
  2. Entry points — main.ts, App.tsx, main.py, Main.java, main.go, Program.cs
  3. Directory structure — list 2–3 levels deep to understand module organization
  4. Key patterns — read 1–2 representative files from each major directory to understand conventions:
    • Naming patterns (files, classes, functions)
    • Import style and module organization
    • Error handling patterns
    • Testing patterns (find test files)
  5. CI/CD — .github/workflows/, Jenkinsfile, .gitlab-ci.yml, cloudbuild.yaml
  6. Docs — README.md, docs/, CONTRIBUTING.md
  7. Content — two patterns to detect:
    • Static content files — static-content/, data/ dirs with TS/JS exports. Map content file → sections → consuming pages
    • File-based content (blog/docs) — content/blog/, posts/, MDX/MD directories. Read 1-2 sample files to extract: frontmatter format (all fields, types, required/optional), file naming convention, cover image path pattern, tags/categories, discovery assets (llms.txt, sitemap config, RSS feed)
  8. UI conventions — grep for icon libs (lucide, solar, phosphor), animation libs (framer-motion, gsap), component libs (shadcn, radix, mui), icon registries
  9. AI tooling — .codeiumignore, .cursorignore, .gitignore — paths AI tools cannot access

2b. Identify Significant Directories

Identify directories warranting their own scoped AGENTS.md. Criteria (any one): 10+ files with distinct responsibility, clear architectural layer, different conventions than parent, public API surface, generated code, infrastructure code.

Common significant directories:

StackSignificant Directories
Java Spring Bootcontroller/, service/, repository/, model/, config/, exception/
Next.js / Reactapp/, components/, lib/, hooks/, api/, middleware/
FastAPI / Pythonrouters/, services/, models/, schemas/, dependencies/
Gocmd/, internal/, pkg/, handler/, store/, middleware/
.NETControllers/, Services/, Models/, Data/, Middleware/

3. Generate Root AGENTS.md

Use the matching stack-specific template from .codex/templates/ as a starting point. If no stack matches, use .codex/templates/universal-agents.template.md. Fill in all sections based on deep scan results from Step 2.

Critical rules:

  • State the tech stack explicitly — this drives Codex role selection and overlay activation
  • Include real setup commands — extracted from config files and CI, copy-pastable
  • Link to ARCHITECTURE.md and TESTING.md in the Architecture reference and Testing Instructions sections
  • Map content architecture (if applicable) — which content files drive which pages. Prevents repeated code_search during content edits
  • Document UI conventions (if applicable) — icon set + variant + registry, animation library, component library
  • Document blog conventions (if applicable) — frontmatter format, file naming, discovery assets. Enables blog-post skill workflow
  • Keep concise — avoid repeating what scoped AGENTS.md files will cover

4. Generate ARCHITECTURE.md

Apply system-architect role for this step. The system architect owns the ARCHITECTURE.md file — creation, updates, and reviews.

Use templates/architecture.template.md as the starting point. Fill in all 11 sections based on the deep scan results from Step 2.

Rules:

  • Mermaid/ASCII diagrams for all visual elements
  • Document what exists now, not aspirations. Include versions
  • Focus on relationships and data flows
  • Monorepos: Root ARCHITECTURE.md (system-wide) + per-subproject for each service with own build config. Skip doc-only, config-only, type-only dirs

5. Generate TESTING.md

Apply qa-engineer role for this step. The QA engineer owns the TESTING.md file — creation, updates, and reviews.

Use templates/testing.template.md as the starting point. Fill in all sections based on the deep scan results from Step 2.

5a. Root TESTING.md

Create TESTING.md at the project root using templates/testing.template.md (root template section). Fill in all placeholders based on deep scan results from Step 2. All sections in the template are required — remove only those marked with <!-- Remove ... --> comments.

Key data sources: test config files → test types and commands; CI pipeline → pipeline stages; directory listing → test organization; .env.example → credential structure.

5b. Per-Service TESTING.md (Monorepos)

For each subproject/service identified in Step 1b, create a scoped TESTING.md using templates/testing.template.md (per-service template section at the bottom of the file).

Rules:

  • Include actual commands — copy-pastable, tested
  • Reference root .env for credentials (test_ prefixed vars), do not duplicate
  • List key test scenarios for critical paths (auth, payments, data mutations)
  • Keep service-specific — do not repeat root TESTING.md content

5c. Single-Project (Non-Monorepo)

For single-project repos, create only root TESTING.md (no per-service files). Include all service-level detail directly in the root file.

6. Generate Scoped AGENTS.md Files

For each significant directory identified in Step 2b, create a scoped AGENTS.md:

# AGENTS.md

## Purpose
[1 sentence: what this directory contains and its role in the architecture]

## Conventions
[Directory-specific patterns, naming, file organization]

## Key Files
[Important files with brief descriptions]

## Patterns
[Code patterns used in this directory — how to add new items]

## Testing
[How to test code in this directory specifically]

## Do NOT
[Directory-specific anti-patterns and constraints]

Rules for scoped AGENTS.md:

  • Never repeat root AGENTS.md content — reference it if needed
  • Be directory-specific — only include information relevant to THIS directory
  • Include "how to add new X" — the most common operation in each directory
  • Keep it short — 20–50 lines. Developers read these frequently
  • State constraints — what should NOT be in this directory

Example

src/controllers/AGENTS.md — Purpose, naming convention ({Resource}Controller.java), injection rules (constructor, never repositories directly), validation (@Valid), "Adding a New Controller" steps.

7. Review and Confirm

Present a summary of all files to be created:

## Project Init Summary

### Files to create:
- [ ] AGENTS.md (root) — [X lines]
- [ ] ARCHITECTURE.md (root) — [X lines]
- [ ] TESTING.md (root) — [X lines]
- [ ] [service-1]/TESTING.md — [X lines] (monorepo only)
- [ ] [service-2]/TESTING.md — [X lines] (monorepo only)
- [ ] src/controllers/AGENTS.md — [X lines]
- [ ] src/services/AGENTS.md — [X lines]
- [ ] ...

### Project map:
[project boundary diagram from Step 1b]

### Tech stack detected:
[list of technologies, frameworks, tools]

Wait for user APPROVE before writing files. User may skip directories, add undetected ones, or adjust content.

8. Write Files

After approval, create all files. For each file:

  1. Write the content
  2. Verify it was created successfully
  3. Report any issues

If updating existing files — show the diff and request confirmation.

9. Verify

After all files are created:

// turbo
find . -name "AGENTS.md" -o -name "ARCHITECTURE.md" -o -name "TESTING.md" | sort

Verify:

  • Root AGENTS.md exists and contains correct tech stack
  • Root AGENTS.md links to TESTING.md in Testing Instructions section
  • Root and per-subproject ARCHITECTURE.md files exist
  • Root TESTING.md exists with all test types, commands, infrastructure
  • Per-service TESTING.md files exist for each subproject (monorepos)
  • All significant directories have scoped AGENTS.md
  • No redundancy between root and scoped files
  • All test commands are accurate and copy-pastable
  • No secrets, PII, or hardcoded credentials in any file (especially .env test values)

Integration

  • Precedes: All other workflows — run this first on a new project
  • Templates: .codex/templates/*-agents.template.md, .codex/templates/architecture.template.md, .codex/templates/testing.template.md
  • Roles: system-architect role (ARCHITECTURE.md creation/review), qa-engineer role (TESTING.md creation/review), cloud-architect role (cloud infrastructure context), devops-architect role (CI/CD architecture context)
  • Skills: test-strategy skill (test strategy, coverage targets)
  • Enables: plan skill, feature-dev skill, bugfix skill, test-local skill, run-tests skill

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.