@getpipher/workspace 0.1.0

package/init-agents/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: workspace-init-agents
+description: Create or improve a project AGENTS.md with intelligent codebase analysis. Host-neutral satellite context file read by Claude Code, Pi, and any AGENTS.md-aware agent.
+argument-hint: ""
+allowed-tools: ["bash", "read", "write", "edit"]
+---
+
+# AGENTS.md Initialization (project satellite)
+
+Bismillah! I'll analyze this codebase and create (or improve) a project `AGENTS.md` — the cross-tool context file that Claude Code, Pi, and any `AGENTS.md`-aware agent read on startup.
+
+> **Hub / satellite model.** This skill generates a **satellite**: a host-neutral file describing *this repo*. It extends — never duplicates — the **global hub** (`~/.claude/CLAUDE.md` / `~/.pi/agent/AGENTS.md`), which already carries persona, dev standards, git conventions, secret rules, etc. A satellite holds **only project-specific** content (overview, architecture, commands, conventions, gotchas). No identity, no generic standards, no host-specific tooling — those belong to the hub.
+
+---
+
+## Step 0 — Migrate legacy `CLAUDE.md` (host decoupling)
+
+`AGENTS.md` is the cross-tool standard (pi prefers it; CC reads it too). `CLAUDE.md` is CC's legacy name. If both exist, the repo double-loads and drifts — normalize to one:
+
+- **`CLAUDE.md` exists, no `AGENTS.md`** → `git mv CLAUDE.md AGENTS.md`, then proceed (treat its content as the seed).
+- **Both exist** → ask the user which to keep; default: merge into `AGENTS.md`, `git rm CLAUDE.md`.
+- **Neither exists** → create `AGENTS.md` from scratch (Step 1+).
+- **`AGENTS.md` exists** → analyze and suggest improvements (don't clobber; preserve accurate content).
+
+When migrating, rephrase any CC-flavored framing host-neutrally: "guidance to Claude Code" → "guidance for AI agents"; drop any persona/standards that belong in the hub.
+
+---
+
+## Discovery Process
+
+### 1. Start with existing documentation
+- Read README.md for project overview and setup
+- Look for `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`
+- Find contribution guidelines (CONTRIBUTING.md)
+
+### 2. Discover commands and workflows
+- Check package.json "scripts" (Node.js)
+- Check Makefile targets
+- Look for justfile, Taskfile, or similar task runners
+- Find language-specific files: Cargo.toml, pyproject.toml, build.gradle, etc.
+- Identify CI/CD configs (.github/workflows/, .gitlab-ci.yml) for standard commands
+
+### 3. Understand architecture
+- Read entry points (main.ts, index.js, main.py, cmd/main.go, etc.)
+- Identify directory structure and its purpose
+- Find configuration files and their significance
+- Understand data flow and key abstractions
+- Note any unconventional patterns or design decisions
+
+---
+
+## What to include (project-specific ONLY)
+
+### Essential Commands
+- **Build**: How to compile/bundle the project
+- **Development**: How to run locally with hot reload/watch mode
+- **Testing**: How to run all tests, a single file, or a specific test
+- **Linting/Formatting**: How to check and auto-fix code style
+- **Type Checking**: For typed languages (TypeScript, Python with mypy, etc.)
+- **Database**: Migrations, seeding, reset commands if applicable
+- **Deployment**: Build for production, deployment commands
+
+### Architecture Insights (High-Level Only)
+Information that requires reading **multiple files** to understand:
+- Overall project structure and *why* it's organized that way
+- Key architectural patterns (e.g., "hexagonal architecture with ports/adapters")
+- Data flow between major components
+- Important design decisions or constraints
+- Where different types of work happen (e.g., "Business logic in services/, API routes in controllers/")
+- Non-obvious relationships between modules
+
+### Project-Specific Context
+- Language/framework versions and constraints
+- Important environment variables or configuration
+- Authentication/authorization approach if applicable
+- External dependencies or services the project integrates with
+- Conventions that aren't obvious from code (naming, file placement)
+
+---
+
+## What to exclude
+
+❌ **Anything in the global hub** — persona/identity, dev standards (2-space indent, error handling rules), git/commit conventions, secret-storage rules, a11y/perf mandates. The hub already injects these every session; duplicating them here causes drift.
+❌ Generic advice ("Write clean code", "Handle errors gracefully")
+❌ Obvious info discoverable by reading one file
+❌ Exhaustive file/directory listings
+❌ Repetition of README content (reference it instead)
+❌ CC-specific framing ("guidance to Claude Code") — the file is host-neutral
+
+---
+
+## Structure
+
+Use this structure (omit sections if not applicable):
+
+```
+<!-- Satellite context file — extends the global hub (~/.claude/CLAUDE.md | ~/.pi/agent/AGENTS.md). Host-neutral; project-specific only. Do not duplicate hub standards here. -->
+
+# {Project Name}
+
+> One-line description of what this project does.
+
+## Repository Overview
+[1-2 paragraphs: what this project does, primary language/framework]
+
+## Architecture and Structure
+[High-level architecture, key design patterns, major components and relationships]
+
+## Development Environment
+[Prerequisites, setup steps, environment variables]
+
+## Common Commands
+[Grouped: Development, Testing, Building, Database, etc.]
+
+## Technology Stack
+[Key dependencies and why, if non-obvious]
+
+## Workflow Guidelines
+[Project-specific workflows: deployment, migrations, feature development]
+
+## Key Files and Locations
+[Only files that are important but hard to discover]
+```
+
+---
+
+## Quality Checklist
+
+Before finalizing, verify:
+- [ ] File is named `AGENTS.md` (no legacy `CLAUDE.md` left alongside)
+- [ ] Header satellite-comment + host-neutral phrasing (no "Claude Code" / "Pi" framing)
+- [ ] No content duplicated from the global hub (standards, persona, conventions)
+- [ ] Commands are copy-pasteable and tested
+- [ ] Architecture adds value beyond README
+- [ ] No generic development advice
+- [ ] No repetition of README (reference it)
+- [ ] Focused on what makes THIS codebase unique
+
+---
+
+## Important Notes
+
+- **If `AGENTS.md` exists**: analyze and suggest specific improvements — don't overwrite wholesale.
+- **Test commands** before documenting (use Bash to verify they work).
+- **Be concise**: quality over quantity — focus on what makes this codebase unique.
+- **Reference, don't repeat**: if README documents something well, point to it.
+- **Required prefix**: every generated file starts with the satellite header-comment + `# {Project Name}`.
+
+---
+
+Alhamdulillah! Let's create documentation that makes future work in this codebase smooth and productive — for any agent, any host. InshaAllah!