Skip to content

getting-started.md

Latest commit

 

History

History
275 lines (194 loc) · 8.8 KB

getting-started.md

File metadata and controls

275 lines (194 loc) · 8.8 KB
Raw

Getting Started

Setup and first use of agentic-config across pi packages and Claude Code plugins.

Prerequisites

  • Pi CLI (pi install available) for pi package setup
  • Claude Code CLI with plugin support (claude plugin install available) for Claude Code setup
  • Git (for Claude marketplace access and git-based pi installs)

Pi is an upstream project separate from agentic-config. agentic-config packages install into Pi and use upstream Pi APIs where needed. See Upstream Pi attribution for source links and ownership boundaries.

Install for pi

The current primary pi install path uses the validated root umbrella package from a git ref.

Team and automation install: pin a release tag

pi install "git:github.com/WaterplanAI/agentic-config@v0.3.0-alpha" -l

The -l flag installs it into the local project config. For a global/user install, remove -l.

Use the equivalent SSH git source for the same repository and tag when needed.

For teams, prefer a committed .pi/settings.json pinned to the release tag so pi can auto-install the same reproducible package set on startup:

{
  "packages": [
    "git:github.com/WaterplanAI/agentic-config@v0.3.0-alpha"
  ]
}

Local testing and development: use a branch ref

pi install "git:github.com/WaterplanAI/agentic-config@main" -l

Use a feature branch name instead of main when testing unpublished pi changes.

Package-root testing during development

The git root install exposes the full shipped pi surface. When you need to validate individual package roots during development, use local package paths such as:

pi install ./packages/pi-compat -l
pi install ./packages/pi-ac-meta -l
pi install ./packages/pi-ac-workflow -l

For bundled package roots such as pi-all, use the staged local testing flow from the Pi Package Adoption Guide.

Publishing the per-package npm surface remains future work. See the Pi Package Adoption Guide for the full install matrix.

Install for Claude Code

Add the marketplace, then install plugins:

claude plugin marketplace add WaterplanAI/agentic-config

claude plugin install ac-workflow@agentic-plugins
claude plugin install ac-git@agentic-plugins
claude plugin install ac-qa@agentic-plugins
claude plugin install ac-tools@agentic-plugins
claude plugin install ac-meta@agentic-plugins
claude plugin install ac-safety@agentic-plugins
claude plugin install ac-audit@agentic-plugins

Enable Auto-Updates (Recommended)

Warning: Auto-updates are disabled by default for third-party marketplaces. Without auto-updates, you must manually run Update marketplace to receive new plugin versions and skills.

  1. Run claude and type /plugins
  2. Navigate to Marketplaces tab
  3. Select agentic-plugins
  4. Select Enable auto-update

This keeps the marketplace and all installed plugins automatically in sync with new releases.

Setup a Project

In any project directory:

Claude Code:

claude
/improve-agents-md setup

Pi:

/skill:ac-tools-improve-agents-md setup

The improve-agents-md skill (part of ac-tools) generates and manages AGENTS.md (CLAUDE.md):

  1. Auto-detects project type (TypeScript, Python, Rust, etc.)
  2. Renders AGENTS.md template with tooling values from tooling.yml
  3. Injects extras (e.g., PEP 723 for Python types)

Supported Project Types

Type Package Manager Type Checker Linter
typescript pnpm tsc eslint
ts-bun bun tsc eslint
python-poetry poetry pyright ruff
python-uv uv pyright ruff
python-pip pip pyright ruff
rust cargo cargo check clippy
generic custom custom custom

Project type is auto-detected or specified with --type flag.

Update

Claude Code:

claude
/improve-agents-md update

Pi:

/skill:ac-tools-improve-agents-md update

Regenerates AGENTS.md with latest template.

Validate

Claude Code:

claude
/improve-agents-md validate

Pi:

/skill:ac-tools-improve-agents-md validate

Checks AGENTS.md is up-to-date with current template and validates project type detection.

Core Commands

Claude Code Pi Description
/improve-agents-md setup /skill:ac-tools-improve-agents-md setup Generate AGENTS.md for new project
/improve-agents-md update /skill:ac-tools-improve-agents-md update Regenerate AGENTS.md with latest template
/improve-agents-md validate /skill:ac-tools-improve-agents-md validate Check AGENTS.md is current
/spec STAGE path /skill:ac-workflow-spec STAGE path Execute single workflow stage
/mux "prompt" /skill:ac-workflow-mux "prompt" Mux-style orchestration on top of pimux

See Plugin Catalog for all skills across 7 plugins.

Choosing the ac-workflow tmux surface

Use these rules of thumb in pi:

  • pimux command/tool: generic long-lived tmux control plane, including inspectable non-mux hierarchies when you do not need a wrapper
  • ac-workflow-mux: mux-style scout/planner/worker coordination on top of pimux
  • ac-workflow-mux-ospec: one explicit spec-stage owner on top of pimux
  • ac-workflow-mux-roadmap: roadmap -> phase -> stage hierarchy on top of pimux

See pimux Workflow Topologies for the communication patterns, nesting depth, and typical agent counts.

Quick examples:

/pimux spawn "Inspect this repo and report the key files."
/pimux spawn "Run in your own tmux session and keep working until done."
/skill:ac-workflow-mux "Compare implementation options and return a plan."
/skill:ac-workflow-mux-ospec PLAN .specs/specs/2026/04/example/001-demo.md
/skill:ac-workflow-mux-roadmap .specs/specs/2026/04/example/001-roadmap.md

Customization

AGENTS.md + Symlinks

  • AGENTS.md -- Primary file with standard guidelines (receives updates)
  • CLAUDE.md -- Symlink to AGENTS.md (for Claude Code)
  • GEMINI.md -- Symlink to AGENTS.md (for Gemini)

Add project-specific customizations directly to AGENTS.md.

What Gets Installed

Pi packages (via pi install):

  • @agentic-config/pi-all for the full shipped surface, or selective @agentic-config/pi-* packages
  • Team rollout is typically versioned in committed .pi/settings.json

Claude Code plugins (via claude plugin install):

  • ac-workflow, ac-git, ac-qa, ac-tools, ac-meta, ac-safety, ac-audit
  • No symlinks -- plugins load from ~/.claude/plugins/cache/

Copied (project-customizable):

  • AGENTS.md -- Project-specific guidelines
  • CLAUDE.md, GEMINI.md -- Symlinks to AGENTS.md

Development Mode

For active development on agentic-config itself:

./dev.sh    # launches claude with all 7 --plugin-dir flags

Troubleshooting

Reinstall plugins:

claude plugin install ac-workflow@agentic-plugins
claude plugin install ac-git@agentic-plugins
claude plugin install ac-qa@agentic-plugins
claude plugin install ac-tools@agentic-plugins
claude plugin install ac-meta@agentic-plugins
claude plugin install ac-safety@agentic-plugins
claude plugin install ac-audit@agentic-plugins

Skill not responding:

  • Use the explicit command form for your harness: /improve-agents-md setup in Claude Code or /skill:ac-tools-improve-agents-md setup in Pi
  • Check plugin is installed: claude plugin list
  • Reinstall if missing: claude plugin install ac-tools@agentic-plugins

Plugin not found:

claude plugin marketplace add WaterplanAI/agentic-config

Uninstall legacy v0.1.x wiring:

./uninstall.sh --project --dry-run   # preview project symlink removal
./uninstall.sh --global --dry-run    # preview global wiring removal

See Migration Guide for details.

Version mismatch:

Claude Code:

claude
/improve-agents-md update

Pi:

/skill:ac-tools-improve-agents-md update

See Also