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-mongodb,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.13.1 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.13.1 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 commands, selected coding profiles, and local 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, profiles, 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
.agents/skills/flutter-workflow/	Complete Flutter pipeline, including references, templates and scripts
docs/project/flutter/, docs/adr/	App-owned Flutter profile and ADR seeds when selected

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 Python, PHP, and Flutter/Dart. JavaScript/TypeScript projects use the three application stack skills below. The node stack remains a detection and compatibility label; the old generic node-conventions skill and its React guidance are retired.

Flutter department pipeline

Select Flutter in the existing stack picker or pass --stacks flutter. This replaces flutter-conventions with flutter-workflow and installs the complete department pipeline inside .agents/skills/flutter-workflow/. The selected Claude mirror contains the same complete skill and resources; selected Cursor installations also receive a task-scoped Flutter rule that can be discovered before Dart files exist. Antigravity reads the canonical skill and root AGENTS instructions directly. See the IDE discovery table for exact paths and explicit invocation in each supported IDE. Installed Flutter guidance focuses on the workflow; source audit records and integration history stay in RepoSeed's internal documentation.

Flutter uses the department pipeline together with compatible universal skills. Only commit-messages, maintain-changelog and pr-description are excluded from Flutter-only installs because their output contracts conflict with the department SOPs. The other 16 universal skills remain, including planning, review, verification and the complete Ponytail family. Mixed installs scope only those three conflicting skills to other stacks. Installations without Flutter are unchanged.

In your coding agent, start with “Initialize the Flutter workflow for this app.” A new app asks orientation first, waits, then collects the remaining kickoff choices before any scaffolding. An existing app audits repository evidence and asks Stay versus Strangler. Adopted apps use their saved decisions. The command installs this workflow; it does not launch a conversation or generate application code, choose packages, or install Flutter.

docs/project/flutter/, docs/adr/, and living app documents are seeded only if missing and survive sync, including --force. Other kit files are managed standards. Legacy retirement and replacement are preflighted together; a conflict defers the Flutter migration so two competing managed workflows are not activated. Sync migrates an older root flutter-ai/ installation: app records move to the documentation paths with local Markdown links updated, and the root kit is removed only after successful copying. Different existing destination content, unknown files or symlinks block migration even under force. Resolve the reported paths and rerun reposeed sync; do not delete app records to clear a conflict. Other stacks and selected coding profiles keep their existing behavior. In monorepos, initialize from the Flutter application directory.

See the integration guide for ownership, migration recovery, verification scope, and the department kit's audit corrections. Use a release containing this integration; from this checkout, use uv run reposeed init /path/to/flutter-app --stacks flutter --yes.

Application stack skills

Stack	Bundled design
node-mongodb	JavaScript/Express/Mongoose: layer-based folders, static services, projection builders, constants, validators, helpers, cron, environment, and Postman workflows
node-postgres	TypeScript/Express/Prisma/PostgreSQL: feature folders, injected controllers/services/repositories, validation, storage, and Prisma architecture/migration workflows
react	React/TypeScript/Vite: feature structure, page/form/tab naming, shared UI, CustomTable, Formik/Yup, and Redux loaders

Choose the application directly in the stack picker or pass --stacks node-postgres, --stacks node-mongodb, or --stacks react. Each initialized project can select only one Node.js backend. React can be combined with either backend, for example --stacks node-postgres,react. Flutter, Python and PHP are in the same picker; there is no separate profile question. An empty project can choose its stack before application code exists.

On first initialization, detection requires both dependencies and distinctive source layout, not just a JavaScript manifest. For example, React requires src/components/custom-table/CustomTable.tsx and src/routes/AppRouting.tsx. Detection examines the target application root, not workspace subpackages; initialize each application or select stacks explicitly for a mixed repository. Two different backends must be initialized in separate application roots. The selection guide documents all matching rules.

Each application stack has an ordinary portable skill with a focused SKILL.md, relative reference files and agents/openai.yaml. It uses the existing canonical library and Claude mirror. AGENTS.local.md connects the selected applications to the shared root guidance. No application boilerplate, Node dependencies, environment values, or database commands are installed or run. The existing Ponytail skills remain shared; the frontend's distinct reuse/layout guidance is included in the React skill.

Selecting a different backend with --stacks replaces the previous backend while retaining React and other selected stacks. Sync preserves the saved choice. For older scripts, the hidden --profiles option and saved/JSON profiles field remain supported: an explicit list replaces that list, and --profiles "" clears it. The one-backend constraint also applies to this compatibility option.

On upgrade, unchanged managed copies of node-conventions (including the old React reference) are removed from both libraries. Deselected profiles use the same retirement path. A locally edited file, extra file, or symlink preserves the whole skill and reports a conflict; entirely untracked skills remain user-owned. --dry-run and sync --check preview these removals. Review conflicts before using --force, which can retire edited tracked files but still preserves untracked additions and symlinks. Existing boilerplate .agents/ rule files outside the managed skill libraries are preserved.

Backend switches check both skill libraries before making changes. If the old backend cannot be retired or the new skill has a file conflict, initialization stops and preserves the previous configuration and files. Resolve the reported paths and rerun the same init --stacks command. Doctor also reports leftover conflicting backend skills.

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.

The documentation skill also chooses interactive architecture, workflow, sequence, dataflow, and lifecycle diagrams for suitable topics. Ask your coding agent: “Use project-understanding to generate this project's documentation with interactive diagrams, then build the website.” It reviews the code, authors the JSON, and uses the pinned Archify browser renderer bundled in RepoSeed. Python prepares the standalone HTML and the user's existing browser draws the diagram. No Node.js, Chromium, npm, runtime download, or automatic installer is required.

For direct authoring, reposeed diagram reference <type> --json locates schemas and examples. reposeed diagram render <type> <input.json> <output.html> --json validates inputs and writes standalone HTML plus a portable receipt. Attach them to a topic as described in the diagram reference. Open the viewer to verify rendering and readability. The receipt distinguishes Python input checks from browser rendering; it does not claim Chromium validation. finalize remains an alias for render. Documentation builds do not independently interpret source code or rewrite diagrams.

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-postgres, node-mongodb, react, 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. Application skills use the saved choice or detect the matching boilerplate on first initialization. Pass --stacks "" and the compatibility option --profiles "" to select only universal skills on a new project; previously selected stacks remain additive on initialized projects.

On an initialized project, --platforms and non-backend stack choices 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 installs Ponytail as part of every initialization, including Flutter. 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 skills keep RepoSeed's clarification, security, accessibility, testing, changelog, and verification requirements authoritative. See src/reposeed/foundation/PONYTAIL.md for usage and activation rules.

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 Agent Skills format. Discovery paths are 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 .
reposeed --version

Use reposeed init or reposeed sync to test this local checkout. Commands with @latest request the published package instead of the local development build.

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