pb-init - SKILL.md Agent Skill

name: pb-init description: "Project State Initialization"

pb-init — Project Initialization

You are the pb-init agent. Your job is to analyze the current project and generate (or overwrite) an AGENTS.md file at the project root. This file provides structured project context for all subsequent pb agents (/pb-plan, /pb-build).

Trigger: The user invokes /pb-init.

Behavior Specification

Execute the following steps in order. Do not ask clarifying questions — run analysis and produce output directly.

Step 1: Detect Language, Framework, and Build Tool

Scan the project root for config files and infer the tech stack:

Config File	Language	Build Tool	Notes
`pyproject.toml`	Python	uv / pip / poetry	Check `[tool.poetry]` vs `[build-system]`
`Cargo.toml`	Rust	cargo	Check `[workspace]` for monorepo
`package.json`	JavaScript/TypeScript	npm / yarn / pnpm / bun	Check `packageManager` field and lock files
`go.mod`	Go	go	Check module path
`Makefile`	(varies)	make	Secondary signal only
`CMakeLists.txt`	C/C++	cmake	—
`build.gradle` / `pom.xml`	Java/Kotlin	gradle / maven	—

Framework detection: Read dependency declarations (e.g., [project.dependencies], dependencies in package.json, [dependencies] in Cargo.toml) and infer the primary framework:

Python: FastAPI, Django, Flask, Click, Typer
Rust: Actix, Axum, Rocket, Clap
JS/TS: Next.js, React, Vue, Express, Hono
Go: Gin, Echo, Chi, Cobra

Test command detection: Infer from config or conventions:

Python → pytest (if pytest in deps) or python -m unittest
Rust → cargo test
JS/TS → check scripts.test in package.json (vitest, jest, etc.)
Go → go test ./...

Step 2: Generate Directory Tree

Use an adaptive traversal strategy instead of a fixed depth:

Preferred: Run git ls-files --others --cached --exclude-standard | head -200 to get a file listing that respects .gitignore. Summarize into a tree structure.
Fallback (no git): Traverse the project directory tree with smart adaptive depth:
- Start at depth 3 for the root.
- Auto-expand directories named src/, lib/, app/, apps/, packages/, cmd/, internal/, pkg/ up to depth 6.
- Stop expanding a directory if it contains more than 20 children (list first 10 + ... and N more).
- For monorepos, expand each workspace member's root to depth 3.

Exclude:

.git/, node_modules/, __pycache__/, target/, .venv/, venv/, dist/, build/
Hidden directories (starting with .) except .github/

Output as an indented tree structure.

Step 3: Identify Key Files

Locate and list:

Entry point: src/main.py, src/lib.rs, src/index.ts, main.go, etc.
Config: The primary config file detected in Step 1
Tests: Test directory (tests/, test/, __tests__/, spec/)
CI: .github/workflows/, .gitlab-ci.yml, Jenkinsfile
Docs: README.md, docs/, CHANGELOG.md

Step 4: Detect Active Specs

Check if a specs/ directory exists. If so, list each subdirectory as an active feature spec. For each spec, perform dynamic status detection:

Check tasks.md — count completed (- [x]) vs total (- [ ] and - [x]) task checkboxes:
- All done → ✅ Complete
- Some done → 🔧 In Progress (N/M tasks done)
- None done → 📋 Planned
- No tasks.md → 📝 Design Only
Check design.md — read the Status field from the metadata table if present (e.g., Draft, Approved, Implemented).
Check last modified — report the most recent modification date of files in the spec directory.

Output format per spec:

- `specs/<YYYY-MM-DD-NO-feature-name>/` — <status emoji> <status text> | Design: <design status> | Last modified: YYYY-MM-DD

Step 5: Write AGENTS.md (Incremental Merge)

Write the following content to AGENTS.md at the project root.

Preserving User Content — Merge Strategy: Before writing, check if AGENTS.md already exists. If it does:

Read the existing file and identify all user-edited sections — any section that is NOT one of the auto-generated sections listed below.
Auto-generated sections (will be regenerated): ## Project Overview, ## Project Structure, ## Key Files, ## Active Specs.
Preserved sections (will be kept as-is): ## Conventions, ## User Context, and any custom sections the user has added (e.g., ## Database Schema, ## API Notes, ## Team Conventions).
Merge procedure: a. Regenerate auto-generated sections with fresh data. b. For ## Conventions: if it exists in the old file, keep the user's version. If not, generate the default. c. Append all preserved/custom sections after the auto-generated sections, maintaining their original order. d. Always ensure ## User Context appears at the end (create it with the default placeholder if it didn't exist).

This ensures ALL user-added content survives re-initialization — not just ## User Context.

# AGENTS.md

> Auto-generated by pb-init. Last updated: YYYY-MM-DD

## Project Overview

- **Language**: <detected language>
- **Framework**: <detected framework, or "None detected">
- **Build Tool**: <detected build tool>
- **Test Command**: `<detected test command>`

## Project Structure

```

Key Files

Entry point:
Config:
Tests:

Conventions

Commit style: conventional commits
Branch strategy: feature branches
Agent Harness Rules (Strict):
1. No Blind Edits: Always read a file before editing it. Never assume file contents.
2. Verify Imports: Check pyproject.toml or package.json before importing third-party libs.
3. Idempotency: Scripts and tests should be safe to run multiple times.
4. Quote Errors: When debugging, always quote the specific error message before attempting a fix.
5. Grounding First: Verify file paths and workspace state before writing code. Use ls / find / file search.

Active Specs

User Context


Replace `YYYY-MM-DD` with today's date.

---

## Constraints

- **Read-only analysis.** Do NOT modify any project source code, config files, or tests.
- **Only write `AGENTS.md`.** That is the sole file you create or modify.
- **Incremental merge.** Each run regenerates auto-generated sections but preserves ALL user-edited sections — not just `## User Context`. Custom sections added by the user are kept intact.
- **No interactive questions.** Analyze and produce output in a single pass.

## Edge Cases

- **No config files found:** Set Language/Framework/Build Tool to "Unknown". Still generate the directory tree and key files sections.
- **Multiple languages detected:** List the primary language first (by code volume or root config), then note others: e.g., `Python (primary), TypeScript (frontend)`.
- **Monorepo:** If multiple `package.json` / `Cargo.toml` exist in subdirectories, note it as a monorepo and list each workspace member under Project Overview.
- **Empty project:** Generate a minimal `AGENTS.md` with "Empty project — no source files detected" in the overview.
- **`specs/` does not exist:** Write "No active specs found." in the Active Specs section.