Metadata-Version: 2.4
Name: reposeed
Version: 0.13.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: jsonschema==4.26.0
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-mongodb,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.13.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.13.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 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](docs/project/flutter-workflow.md#native-ide-discovery)
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](docs/project/flutter-workflow.md) 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](docs/project/coding-profiles.md) 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](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.

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](src/reposeed/foundation/skills/universal/project-understanding/references/diagrams.md).
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](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-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`](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:

```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 Agent Skills format. Discovery paths are 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 .
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:

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