RepoSeed

Initialize a project-wide AI coding foundation for Codex, Claude Code, Cursor, and Google Antigravity with one uv command:

uvx reposeed@latest init

uv is the only prerequisite. It runs RepoSeed in an isolated Python environment and automatically provides a compatible Python interpreter when the machine does not already have one. Graphify is a pinned dependency of that same environment, so RepoSeed never bootstraps uv, invokes pip, or relies on a global graphify executable.

RepoSeed supports Python 3.10 through 3.14. Every advertised version is tested in CI on pushes and pull requests.

The initializer installs portable Agent Skills, shared engineering guidance, repository-aware commands, platform adapters, the bundled Ponytail minimalism layer, and the managed Graphify setup. It is safe to rerun: marked instruction blocks are merged, generated files are tracked by hash, and local edits are reported as conflicts instead of silently overwritten.

Quick start

Run interactively from the project you want to configure:

uvx reposeed@latest init

Or configure it non-interactively:

uvx reposeed@latest init ./my-project \
  --platforms codex,claude,cursor,antigravity \
  --stacks node,python \
  --yes

Preview without writing:

uvx reposeed@latest init --dry-run --yes

Validate an installation:

uvx reposeed@latest doctor

Pin a specific RepoSeed release when reproducibility across a team or CI matters:

uvx reposeed@0.11.0 init --yes

Keep an initialized project current

Synchronize an existing project with the assets bundled by the newest published RepoSeed release:

uvx reposeed@latest sync

Using @latest matters: uv can reuse the cached version of an unversioned uvx tool. RepoSeed does not update its own package or fetch skill content at runtime; sync applies only the trusted assets in the version uv executes. Use an exact command such as uvx reposeed@0.11.0 sync for a reproducible upgrade.

Preview the plan, or check it in CI without writing:

uvx reposeed@latest sync --dry-run
uvx reposeed@latest sync --check

--check returns 0 when the project is current and 2 when files need to be created or updated, or when a local edit needs review.

What is generated

Path	Purpose
AGENTS.md	Shared, always-on engineering behavior in a managed block
AGENTS.local.md	Detected project commands and repository-specific notes
CHANGELOG.md	Dated, commit-aligned project history for humans and agents
.agents/skills/	Canonical Agent Skills for Codex, Cursor, and Antigravity
CLAUDE.md	Claude bridge to the shared instructions, when selected
.claude/skills/	Managed Claude Code skill mirror, when selected
.reposeed/config.json	Selected platforms, stacks, and pinned integrations
.reposeed/graphify.json	Pinned Graphify version and managed platforms
.reposeed/manifest.json	File hashes used for conflict-safe updates
.reposeed/guides/	Operating, platform, Ponytail, and Graphify references

Universal skills cover automatic prompt enhancement, clarification, planning, diagnosis, test-driven development, code review, evidence-based completion, changelog maintenance, commits, pull requests, security review, project understanding, compounding repository knowledge, and Ponytail's minimum-correct-solution workflows. Stack skills are available for Node.js/TypeScript, Python, PHP, and Flutter/Dart. Stack detection reads the target project's standard manifests and lockfiles.

prompt-enhancer and clarify-before-building work together automatically: inspect available context, resolve material gaps with the user, and form a concise execution brief from confirmed requirements. They share one clarification pass, avoid invented assumptions, and continue into the requested work once it is clear. A request to improve only a prompt returns the prompt instead.

The shared instructions and security-checklist also require an immediate pause when a user supplies actual or suspected raw credentials. The agent must avoid repeating or using them, request revocation or rotation and a sanitized request, and continue only after recovery is confirmed. Clear placeholders, redacted examples, and non-secret identifiers remain usable. These are agent instructions; RepoSeed does not intercept chat messages or technically enforce refusal in the host application.

Project understanding and handovers

For this repository, start with the project knowledge index.

Project guides, flow explanations, onboarding, and handovers are handled by $project-understanding. It connects behavior, data, business rules, decisions, failure paths, and tests to evidence, keeping confirmed intent and unknowns distinct. Meaningful changes update the affected knowledge alongside the code.

Project-specific documents and their evidence manifest are project-owned: initialization and synchronization do not create, replace, or reset them. The skill reuses existing documentation. Its default entry point is docs/project/index.md, with tracking in docs/project/knowledge.json. See the skill and manifest reference.

After reviewing a topic, run reposeed knowledge record . --topic <name>, using a name from its manifest, then reposeed knowledge check .. The read-only check detects source and document changes, including additions and deletions inside declared directories. It exits 2 for stale, partial, missing, or uncovered knowledge; invalid configuration exits 1. A pass establishes declared local file coverage and matching fingerprints, not explanation accuracy, remote runtime state, or developer understanding.

Run check in existing CI to cover manual edits as well as AI changes. Record topics only after review, never automatically in CI. RepoSeed installs the workflow; building the initial guide and enabling CI are separate project actions. From this checkout, invoke commands with uv run reposeed. Other projects need a release containing this feature before using the commands.

Preview the guide with reposeed knowledge serve ., then open http://127.0.0.1:8000/. MkDocs and its Python dependencies are included in the normal RepoSeed installation. The website adds navigation, search, Mermaid diagrams, readable source links, and visible knowledge status. The pinned Mermaid renderer, theme, and search assets are served locally; the default preview needs no additional install step or CDN access. Normal initial RepoSeed installation still needs network access or cached packages.

reposeed knowledge build . exports the site to .reposeed/site by default. Existing MkDocs configuration is preserved; otherwise a project-owned mkdocs.yml is created. Exports include referenced source snapshots. Neither command publishes the site or records a review. See the preview reference for configuration, dependencies, output protection, and verification.

Commands and options

reposeed init [directory]
  -p, --platforms <names>  codex, claude, cursor, antigravity
  -s, --stacks <names>     node, python, php, flutter
  -y, --yes                accept defaults without prompts
      --no-graphify        skip managed Graphify integration
      --graphify-git-hooks explicitly enable the default Graphify Git hooks
      --no-graphify-git-hooks skip or remove the default Graphify Git hooks
      --dry-run            show planned changes
      --force              replace conflicting generated files
      --json               emit machine-readable output

reposeed sync [directory]
      --dry-run            show planned changes without writing
      --check              exit 2 when synchronization is needed
      --force              replace conflicting generated files
      --json               emit machine-readable output

reposeed doctor [directory]
      --json               emit machine-readable output

reposeed knowledge check [directory] [--manifest <path>] [--json]
      check declared project knowledge coverage and freshness
reposeed knowledge record [directory] --topic <name> [--manifest <path>] [--json]
      record source fingerprints after reviewing one topic
reposeed knowledge serve [directory] [--port 8000] [--config-file <path>] [--manifest <path>]
      preview with live reload on the loopback interface
reposeed knowledge build [directory] [--site-dir <path>] [--config-file <path>] [--manifest <path>]
      export a static knowledge website

reposeed graphify <arguments...>
      run the pinned Graphify CLI in the same uvx environment

Human-facing commands use terminal-aware color, structured summaries, and readable status output. Rich styling is removed automatically when output is piped or redirected, and NO_COLOR=1 disables color explicitly. --json always bypasses presentation output so automation receives plain JSON only.

With --yes, all four platforms are selected and application stacks are auto-detected unless explicit lists are supplied. Pass --stacks "" for universal skills only.

On an initialized project, --platforms and --stacks are additive. For example, initializing Antigravity first and later running with --platforms codex retains Antigravity and adds Codex. Removing a platform is never inferred from an omitted command-line value.

Safe update behavior

AGENTS.md, AGENTS.local.md, and CLAUDE.md use explicit managed markers. Only the content between those markers is updated, preserving project guidance and sections maintained by tools such as Graphify.

Other generated files are replaced only when their current content matches the last manifest. init and sync use the same manifest-backed reconciliation engine: newly bundled files are created, unchanged managed files are updated, and local edits are preserved as conflicts with exit code 2. Review the change and rerun with --force only when replacement is intentional.

The initializer never deletes stale platform files automatically. Removing configuration is a destructive decision and remains explicit. --force only authorizes replacement of conflicting RepoSeed-generated files; it does not authorize replacement of pre-existing Graphify skills, rules, or workflows.

Ponytail

RepoSeed bundles an adapted copy of Ponytail v4.9.0 as part of every initialization. Its default ladder asks whether code is needed, then prefers repository reuse, the standard library, native platform features, installed dependencies, and finally the smallest coherent new implementation.

The ponytail, ponytail-review, ponytail-audit, ponytail-debt, ponytail-gain, and ponytail-help skills are installed in the canonical .agents/skills/ library and mirrored to .claude/skills/ when Claude Code is selected. RepoSeed ships the skills directly; it does not install Ponytail's native plugin manifests, JavaScript lifecycle hooks, status line, or user-level state. No Node.js runtime or separate download is required during project initialization.

The adaptation keeps RepoSeed's clarification, security, accessibility, testing, changelog, and verification requirements authoritative. See src/reposeed/foundation/PONYTAIL.md for the source pin, behavior differences, update procedure, and upstream MIT license.

Graphify

Graphify 0.9.49 is enabled by default and pinned in pyproject.toml. During init, RepoSeed verifies the installed dependency and invokes it as:

<uvx-python> -m graphify <platform> install --project

This avoids every global PATH and interpreter-discovery problem. The native Graphify skill is also adapted to resolve the exact RepoSeed environment through uvx. Its core setup will not recommend pip install, uv tool install, or an unpinned Graphify upgrade. The managed package intentionally omits LLM backend extras.

An existing standalone Graphify installation is left installed and unchanged. If a project already contains a complete Graphify adapter, initialization keeps its files and only refreshes the recognizable RepoSeed runtime block and Graphify hook command. If an adapter is partial, missing files are repaired and all pre-existing Graphify-owned files are restored afterward. Existing graphify-out/ data is never changed by init.

On a project where Graphify is already managed, --no-graphify skips adding it to newly selected platforms; it does not uninstall or disable the platforms that already use it.

Initialization configures the integration but does not build a graph because it may run before a project contains source code. The managed integration is strictly AST-only: it never sends repository content to an LLM, extracts semantic document/media context, or labels communities with an LLM. Build the code graph from the terminal:

uvx reposeed graphify extract . --code-only

The wrapper adds --code-only when omitted, adds --no-label to cluster-only, and rejects semantic-only commands and flags. Installed agent skills carry the same mandatory policy.

The graph is written under graphify-out/. After code changes, run:

uvx reposeed graphify update .

Initialized guidance starts with targeted source slices and budgeted query, path, or explain calls instead of loading full reports or raw graph data. The managed update command is a complete AST-only refresh: it updates symbols, calls, imports, inheritance, and other structural relationships with no LLM or API cost. Documents, papers, images, audio, and video are outside the managed graph's scope.

Code graphs refresh automatically after commits and branch switches because Graphify's Git hooks are installed by default. For a non-Git project or a team that does not want repository hooks, opt out explicitly:

uvx reposeed@latest init --no-graphify-git-hooks

Graphify adds to existing Git hooks instead of replacing them and also registers its merge driver for graphify-out/graph.json. The initializer records the setting and doctor verifies the installation. This automation handles code and deletions and never schedules semantic work.

See src/reposeed/foundation/GRAPHIFY.md for the operating model.

Platform conventions

The canonical layout follows the open Agent Skills specification. Current discovery paths and primary sources are recorded in PLATFORM_SUPPORT.md.

Development and publishing

Development requires uv; Python and all dependencies are managed by it:

uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv build --no-sources

Install the current checkout as a local editable uv tool while developing:

uv tool install --editable --force .
uvx reposeed --version

Build the release artifacts, test the wheel through uvx, then publish only the two intended release files to PyPI:

uv build --no-sources
uvx --refresh --from ./dist/reposeed-0.11.0-py3-none-any.whl reposeed --version
uv publish ./dist/reposeed-0.11.0.tar.gz ./dist/reposeed-0.11.0-py3-none-any.whl