{
  "markdown": "# specrails-core\n\n[![CI](https://github.com/fjpulidop/specrails-core/actions/workflows/ci.yml/badge.svg)](https://github.com/fjpulidop/specrails-core/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/specrails-core.svg)](https://www.npmjs.com/package/specrails-core)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nSpecrails Core installs specification-driven development workflows into a project. It gives your AI CLI three baseline roles—architect, developer and reviewer—plus provider-native commands, OpenSpec integration and project conventions. You choose the provider; Core supplies the workflow and its local artifacts.\n\nUse Core directly from Claude Code, Codex CLI, Gemini CLI or Kimi Code. For mission conversations, a shared project board, execution loops and delivery controls, use [Specrails Desktop](https://github.com/fjpulidop/specrails-desktop).\n\nThis README describes the current source tree. `npx specrails-core@latest` installs the published package, not unmerged changes. Check the [release notes](https://github.com/fjpulidop/specrails-core/releases), or [build this checkout](#develop-from-source) when testing unreleased work.\n\n## Quick start\n\nYou need **Node.js 20.19.0+**, Git and at least one installed, authenticated AI CLI. A provider may impose a higher Node or operating-system requirement than Core itself. Install providers through their own supported installation flow.\n\nFrom the project you want to configure:\n\n```sh\nnpx specrails-core@latest init --provider claude\n```\n\nChoose `claude`, `codex`, `gemini` or `kimi`. The default installer collects agent and model configuration interactively. For a non-interactive installation using defaults:\n\n```sh\nnpx specrails-core@latest init --yes --provider claude\n```\n\nCore 5 installs the baseline roles and workflows directly; it does not invoke a model for an enrichment phase. Installing dependencies or OpenSpec may require network access. Review the generated project configuration before running an implementation.\n\nOpen the selected AI CLI in that project and use its native workflow syntax:\n\n| Provider | Executable | Implement | Batch | Retry |\n| --- | --- | --- | --- | --- |\n| Claude Code | `claude` | `/specrails:implement` | `/specrails:batch-implement` | `/specrails:retry` |\n| Codex CLI | `codex` | `$implement` | `$batch-implement` | `$retry` |\n| Gemini CLI | `gemini` | `/specrails:implement` | `/specrails:batch-implement` | `/specrails:retry` |\n| Kimi Code | `kimi` | `/skill:specrails-implement` | `/skill:specrails-batch-implement` | `/skill:specrails-retry` |\n\nFor example, enter this **inside Claude Code or Gemini CLI**, not in your shell:\n\n```text\n/specrails:implement \"add keyboard navigation to the settings page\"\n/specrails:implement #1, #2\n```\n\nKimi integration targets Kimi Code 0.27.0+. Its headless path uses the installed `.kimi-code/specrails/run-skill.mjs` helper to activate the workflow before calling the external CLI; passing a slash command directly to `kimi -p` is not equivalent. See [Kimi setup](docs/user-docs/getting-started-kimi.md) and [provider pipeline contracts](docs/user-docs/provider-pipelines.md).\n\n## How implementation works\n\n```text\nSpecification → Architecture → Implementation → Review → Delivery\n                sr-architect   sr-developer      sr-reviewer\n```\n\nThe architect produces the OpenSpec proposal, design and tasks. The developer implements the agreed work. The reviewer checks the result against the spec and project verification commands. Delivery follows the configured Git workflow and the execution owner's policy.\n\nThe current source installs a local pipeline helper for persisted phase state, explicit role handoffs and verification receipts. Retry resumes the first incomplete or invalid phase; it does not treat an earlier success as valid after its inputs change. A batch retains its tickets' requirements and repository identities in an aggregate change. See the [pipeline contract](docs/user-docs/provider-pipelines.md) for the execution context and validation limits.\n\nStandalone automatic delivery can create branches, commits, pushes and pull requests when enabled. Set the project's Git workflow deliberately; model execution and repository writes are real operations, not a preview by default. GitHub pull requests additionally require an authenticated `gh` CLI.\n\nWhen a host such as Desktop owns worktrees and delivery, it sets `SPECRAILS_GIT_AUTO=false` and supplies the execution context. Core then leaves branch creation, commits, pushes and PRs to that host. Multi-repository contexts must explicitly identify the selected repositories and the OpenSpec/backlog owner; an additional readable folder is not automatically an implementation target.\n\n## Installed files and ownership\n\nStandalone installation normally copies committable artifacts into the repository and uses a shared framework store under `~/.specrails/`. Relocated installations, including Desktop-managed workspaces, can keep framework links and project artifacts outside the checkout. The resolved workspace determines where these files live.\n\n| Surface | Purpose |\n| --- | --- |\n| `.claude/`, `.codex/`, `.gemini/`, `.kimi-code/` | Selected provider's agents, commands or skills |\n| `openspec/` | Specifications and change artifacts |\n| `.specrails/config.yaml` and `install-config.yaml` | Project workflow and installation configuration |\n| `.specrails/rules/` and `agent-memory/` | Coding conventions and retained agent notes |\n| `.specrails/runtime/` and `pipeline/` | Installed execution helper and run state in the current source |\n| `.specrails/local-tickets.json` | Local backlog, when that backlog provider is selected |\n| `.specrails/profiles/` | User-owned profiles and model/routing choices |\n\nLocal tickets do not require GitHub or Jira. External backlog integrations require their own credentials and configuration. See [local tickets](docs/local-tickets.md) and [backlog migration](docs/migration-guide.md).\n\nManaged files can be regenerated by updates. Keep extensions in documented user-owned locations rather than relying on edits to generated agents surviving an update.\n\n## Extend the agents\n\nProfiles can select models and route tasks to additional specialists where the provider workflow supports them. Keep the three baseline roles, then add your custom agents and routing. The profile schema is [schemas/profile.v1.json](schemas/profile.v1.json).\n\n```sh\nnpx specrails-core@latest profile validate .specrails/profiles/default.json\n```\n\nThe installer reserves these extension paths:\n\n- `.specrails/profiles/**`\n- `.claude/agents/custom-*.md`\n- `.kimi-code/skills/custom-*/**`\n\nUse the `custom-` prefix for protected custom roles. The legacy nested Kimi custom-role layout is preserved during migration as well. Other provider-managed surfaces are not a blanket guarantee that arbitrary local changes survive regeneration. See [customization](docs/customization.md) for the broader configuration model.\n\n## Update an existing project\n\nUpdating the executable and refreshing a project's artifacts are separate operations. From the project directory:\n\n```sh\nnpx specrails-core@latest --version\nnpx specrails-core@latest update --dry-run\nnpx specrails-core@latest update\nnpx specrails-core@latest doctor\n```\n\nUse an exact published package version instead of `latest` when reproducibility matters. The selected CLI supplies the framework bytes; the current source rejects an older CLI overwriting a newer installed framework. It retains recovery information for failed updates and does not report a complete upgrade after a partial component refresh.\n\nExisting provider selections are preserved by the current update implementation. Installing support for an additional provider does not require discarding the other provider's managed artifacts. See [installation and update consistency](docs/user-docs/core-updates.md) for version checks, copied versus linked workspaces, concurrent updates and rollback behavior.\n\n### Migrating from Core 4\n\nCore 5 removes the `enrich` command, the quick/full installation tiers and the previously bundled non-core specialist agents. `init` performs deterministic placement instead of launching the old enrichment wizard.\n\nBefore upgrading, review customizations and profiles that refer to removed agents. Move any specialist you want to retain into a protected `custom-*` role and update its profile reference. The migration removes installer-owned legacy artifacts; protected profiles and custom agents remain user-owned.\n\nDesktop must support the selected Core lifecycle. Current Desktop source supports Core 5, but older installed Desktop releases can differ. Updating this repository or the global CLI alone does not upgrade a running Desktop application or every project's copied artifacts.\n\n## Develop from source\n\nCore uses one npm dependency tree. Node **20.19.0+** is the package minimum; CI exercises the declared platform/runtime matrix.\n\n```sh\ngit clone https://github.com/fjpulidop/specrails-core.git\ncd specrails-core\nnpm ci\nnpm test\n```\n\n`npm test` builds `dist/`, checks types and runs the tests. To use the current checkout against a separate project:\n\n```sh\nnpm run build\nnode bin/specrails-core.mjs --version\nnode bin/specrails-core.mjs init --root-dir /absolute/path/to/project --provider codex\n```\n\nThat final command installs into the target project. Use a disposable fixture when testing installation behavior. No global npm install is needed to execute this checkout.\n\n| Command | Purpose |\n| --- | --- |\n| `npm run build` | Compile the installer and runtime |\n| `npm run typecheck` | Check production and test types |\n| `npm test` | Build, typecheck and run tests |\n| `npm run test:coverage` | Build and run the coverage suite |\n| `npm run test:scripts` | Run release and package guard regressions |\n| `npm run check:package` | Build, install and verify a temporary npm consumer |\n| `npm run ci` | Run local type, release, coverage and package checks |\n| `npm pack` | Build and create a package tarball without publishing |\n\nSee [CI and releases](docs/ci-cd.md) for platform gates and publication requirements. Tests with simulated provider processes do not establish live compatibility with every CLI version, and an installer test does not prove a model will successfully implement every requested feature.\n\n## Data, security and documentation\n\nCore's configuration, specs and run state are local files. Provider CLIs still send supplied context to their configured model services; package installation, GitHub/Jira and MCP integrations may also use the network. Model usage is billed according to your provider. Review the repository's commands and agent permissions before execution.\n\n- [CLI reference](docs/user-docs/cli-reference.md)\n- [Provider pipeline contracts](docs/user-docs/provider-pipelines.md)\n- [Core update consistency](docs/user-docs/core-updates.md)\n- [Local tickets](docs/local-tickets.md)\n- [Documentation index](docs/README.md)\n- [Contributing](CONTRIBUTING.md), [security reporting](SECURITY.md) and [changelog](CHANGELOG.md)\n\nSpecrails Core is available under the [MIT license](LICENSE). Development can be supported through [Ko-fi](https://ko-fi.com/D1D81Y002C).\n",
  "bytes": 11249,
  "sha": "9982a5d28a0c350866c8d1ecd8b86a1a428ba964e3f4eac65cb2a0f37c62a5b3",
  "repo_slug": "fjpulidop/specrails-core",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_fjpulidop_specrails_core_specrails_265a8b93/readme"
}