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.9.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.9.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

Universal skills cover clarification, planning, diagnosis, test-driven development, code review, evidence-based completion, changelog maintenance, commits, pull requests, security review, 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.

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 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.9.0-py3-none-any.whl reposeed --version
uv publish ./dist/reposeed-0.9.0.tar.gz ./dist/reposeed-0.9.0-py3-none-any.whl