pb-init

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:

1. Preferred: Run git ls-files --others --cached --exclude-standard | head -200 to get a file listing that respects .gitignore. Summarize into a tree structure.
2. 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:

1. 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
2. Check design.md — read the Status field from the metadata table if present (e.g., Draft, Approved, Implemented).
3. 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:

1. Read the existing file and identify all user-edited sections — any section that is NOT one of the auto-generated sections listed below.
2. Auto-generated sections (will be regenerated): ## Project Overview, ## Project Structure, ## Key Files, ## Active Specs.
3. 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).
4. 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

<list of specs/ directories with dynamic status, or "No active specs found.">

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.