Metadata-Version: 2.4
Name: reposeed
Version: 0.11.0
Summary: Initialize portable AI coding standards and skills for Codex, Claude Code, Cursor, and Antigravity.
Keywords: agent-skills,codex,claude-code,cursor,antigravity,ai-coding
Author: RepoSeed contributors
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: graphifyy==0.9.49
Requires-Dist: mkdocs==1.6.1
Requires-Dist: rich>=15,<16
Requires-Dist: rich-argparse>=1.8,<2
Requires-Python: >=3.10, <3.15
Description-Content-Type: text/markdown

# RepoSeed

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

```bash
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:

```bash
uvx reposeed@latest init
```

Or configure it non-interactively:

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

Preview without writing:

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

Validate an installation:

```bash
uvx reposeed@latest doctor
```

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

```bash
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:

```bash
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:

```bash
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](docs/project/index.md).

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](src/reposeed/foundation/skills/universal/project-understanding/SKILL.md)
and [manifest reference](src/reposeed/foundation/skills/universal/project-understanding/references/tracking.md).

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](src/reposeed/foundation/skills/universal/project-understanding/references/preview.md)
for configuration, dependencies, output protection, and verification.

## Commands and options

```text
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`](https://github.com/DietrichGebert/ponytail/tree/0a4dd63ad4541f4f655c4108a295916f3c1d8fda)
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`](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:

```text
<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:

```bash
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:

```bash
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:

```bash
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`](src/reposeed/foundation/GRAPHIFY.md)
for the operating model.

## Platform conventions

The canonical layout follows the open
[Agent Skills specification](https://agentskills.io/specification). Current
discovery paths and primary sources are recorded in
[`PLATFORM_SUPPORT.md`](src/reposeed/foundation/PLATFORM_SUPPORT.md).

## Development and publishing

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

```bash
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:

```bash
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:

```bash
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
```
