Metadata-Version: 2.4
Name: akiforge
Version: 0.2.2
Summary: Portable AI coding-agent harness engine
Author: niks0501
Maintainer: niks0501
License: UNLICENSED — no public license granted
Project-URL: Homepage, https://github.com/niks0501/AkiForge
Project-URL: Repository, https://github.com/niks0501/AkiForge
Project-URL: Issues, https://github.com/niks0501/AkiForge/issues
Project-URL: Documentation, https://github.com/niks0501/AkiForge/tree/main/docs
Project-URL: Changelog, https://github.com/niks0501/AkiForge/releases
Keywords: coding agents,Codex,OpenCode,developer tooling,harness
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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-Python: >=3.11
Description-Content-Type: text/markdown

# AkiForge — Portable Agent Harness

AkiForge is a portable, terminal-first harness engine for Codex and OpenCode.
It gives coding agents the project-specific rules, runtime boundaries, and
verification commands they need without loading an entire handbook into every
conversation. One committed project profile works across both platforms, while
the globally installed engine supplies reusable policy, adapters, upgrade
planning, structured results, and an optional local dashboard.

## What AkiForge can do

- Detect a project stack and create a reviewed runtime profile for host or
  Docker Compose execution.
- Keep agent context small by loading security, frontend, backend, database,
  testing, deployment, and review rules only when relevant.
- Route tiny, normal, and high-risk work through appropriately strict
  implementation and review workflows.
- Enforce approval boundaries for dependencies, migrations, destructive data,
  deployment, credentials, Git publication, and other sensitive operations.
- Run preflight and application checks in the configured environment and
  report `PASS`, `PASS_WITH_GAPS`, `FAIL`, or `INCOMPLETE` truthfully.
- Generate deterministic Codex and OpenCode adapters from one canonical policy.
- Initialize a thin project contract, adopt supported legacy installations, and
  preview or apply contained project upgrades with conflict preservation.
- Bridge a supported 0.1 thin contract to the 0.2 contract through a packaged,
  reviewed, atomic migration with explicit rollback.
- Update or downgrade the global engine independently from project files.
- Recognize declared external tools and report bounded readiness facts without
  installing, updating, executing, or certifying them.
- Return stable text and JSON results, expose an optional token-protected
  read-only localhost API, and visualize project state in an optional dashboard.

AkiForge does not replace Codex or OpenCode chat, install missing project tools,
start containers, run migrations, deploy, read credentials, or repair a runtime
without explicit authorization.

## Core idea

```text
global AkiForge engine
    +--> canonical policy, schemas, adapters, runtime, verification
    +--> CLI / JSON / local API / dashboard share typed services
                    |
                    v
thin committed project contract
    +--> AGENTS.md
    +--> .harness/project.json
    +--> .harness/lock.json
    +--> selected generated Codex/OpenCode adapters
```

Tiny changes should remain tiny. High-risk work can escalate to planning, independent review, full verification, security checks, and rollback notes.

## Install and initialize

Install the engine once. `uv tool` is preferred; `pipx` is supported:

```bash
uv tool install akiforge
akiforge --version
akiforge resource-health
```

Preview a thin contract for a new repository, apply it only after review, then
check the configured runtime and application:

```bash
akiforge --project /path/to/project init --profile all --check
akiforge --project /path/to/project init --profile all --apply
akiforge --project /path/to/project adapter validate
akiforge --project /path/to/project codex configure --check
akiforge --project /path/to/project codex configure --apply
akiforge --project /path/to/project project preflight
akiforge --project /path/to/project verify targeted
```

Use `--profile codex`, `--profile opencode`, or `--profile all` for one or both
platforms. Codex hooks remain inactive until the explicit configuration apply.
Review and commit the managed contract plus
`.harness/project.json`; do not edit generated `.harness/lock.json` manually.

The official lifecycle is:

```text
install -> init -> review profile -> preflight -> verify
        -> update engine independently -> preview/apply project upgrade or migration
```

Existing vendored projects use `project adopt`, never a fresh sync:

```bash
akiforge --project /path/to/legacy-project project adopt --check
akiforge --project /path/to/legacy-project project adopt --apply
```

See the [complete guide](https://github.com/niks0501/AkiForge/blob/main/GUIDE.md),
[installation](https://github.com/niks0501/AkiForge/blob/main/docs/install.md),
[project initialization](https://github.com/niks0501/AkiForge/blob/main/docs/project-init.md),
[engine update](https://github.com/niks0501/AkiForge/blob/main/docs/update.md),
[legacy adoption](https://github.com/niks0501/AkiForge/blob/main/docs/legacy-adoption.md),
[project migration](https://github.com/niks0501/AkiForge/blob/main/docs/project-migration.md), and
[rollback](https://github.com/niks0501/AkiForge/blob/main/docs/rollback.md). The public package and maintainer publication
boundaries are in [Public Distribution](https://github.com/niks0501/AkiForge/blob/main/docs/public-distribution.md) and the
[release runbook](https://github.com/niks0501/AkiForge/blob/main/docs/releasing.md).
Legacy command boundaries are in
[Command Migration](https://github.com/niks0501/AkiForge/blob/main/docs/command-migration.md).
Ownership and supported customization are defined in
[Customization](https://github.com/niks0501/AkiForge/blob/main/docs/customization.md),
with the engine/contract matrix in
[Compatibility](https://github.com/niks0501/AkiForge/blob/main/docs/compatibility.md)
and failure semantics in
[Runtime Resilience](https://github.com/niks0501/AkiForge/blob/main/docs/runtime-resilience.md).
External-tool ownership and readiness are in
[External Tool Readiness](https://github.com/niks0501/AkiForge/blob/main/docs/external-tools.md),
with the Graphify-specific
[workflow](https://github.com/niks0501/AkiForge/blob/main/docs/external-tools/graphify.md).

The public package exposes its Python source and bundled resources. The
repository currently grants no public software license; the package metadata
states that explicitly. Publishing authority belongs to the protected release
workflow and PyPI Trusted Publishing, not to package secrecy.

## Main commands

| Command | Purpose |
|---|---|
| `akiforge doctor` | Check the installed engine and environment. |
| `akiforge --project PATH status` | Show runtime, versions, verification, adapters, and conflicts. |
| `akiforge --project PATH project preflight` | Probe the declared runtime without repair or fallback. |
| `akiforge --project PATH verify targeted` | Run focused configured application checks. |
| `akiforge --project PATH verify full` | Run broad configured application checks. |
| `akiforge --project PATH adapter check` | Validate generated adapter freshness. |
| `akiforge --project PATH adapter validate` | Reject dangling thin-contract references. |
| `akiforge --project PATH codex configure --check` | Preview safe Codex hook activation. |
| `akiforge --project PATH tool list` | List recognized external tools without live checks. |
| `akiforge --project PATH tool show graphify` | Show Graphify metadata and display-only guidance. |
| `akiforge --project PATH tool doctor` | Check only declared external tools. |
| `akiforge --project PATH tool doctor graphify` | Check Graphify explicitly with a bounded readiness probe. |
| `akiforge --project PATH project upgrade --check` | Preview a project-contract upgrade. |
| `akiforge --project PATH project upgrade --apply` | Apply the reviewed upgrade with conflict preservation. |
| `akiforge --project PATH project upgrade --rollback OPERATION_ID` | Restore an applied project upgrade when its files have not drifted. |
| `akiforge --project PATH project migrate --check` | Preview the exact packaged 0.1-to-0.2 contract migration. |
| `akiforge --project PATH project migrate --apply --review-token TOKEN` | Apply an unchanged migration preview atomically. |
| `akiforge --project PATH project migrate --rollback OPERATION_ID` | Restore the exact pre-migration project bytes. |
| `akiforge update --check` | Check the globally installed engine. |
| `akiforge update` | Update the engine through its recognized manager. |
| `akiforge update --version VERSION` | Restore an exact engine version through its manager. |

External-tool commands report readiness, not compatibility. They never install
or update the tool, execute its native workflow, parse its output, or claim an
artifact is correct or fresh. See [External Tool Readiness](https://github.com/niks0501/AkiForge/blob/main/docs/external-tools.md)
before adding the optional `.harness/external-tools.json` declaration.

## Optional local dashboard

Start the dashboard for one explicit project:

```bash
akiforge --project /path/to/project dashboard
```

Open the exact token-bearing URL printed in the terminal. The dashboard shows:

- the active project, runtime probes, gaps, and manual checks;
- the latest valid verification report;
- engine, contract, profile-schema, and adapter status;
- the current project-upgrade plan and conflict list.

Read views do not write the project. Upgrade apply requires review of the exact
plan and an explicit checkbox; stale plans are rejected. Local conflict files
are preserved while packaged candidates are staged under `.harness/incoming`.
Every dashboard action has a CLI equivalent, and stopping or removing the
dashboard does not affect the engine or project contract.

There is no remote mode, CORS, chat, shell, credential store, generic file
browser, or background mutation. See
[Optional local dashboard](https://github.com/niks0501/AkiForge/blob/main/docs/dashboard.md) for usage, security controls,
keyboard navigation, troubleshooting, and manual test steps.

## Missing tools are blockers

AkiForge does not search Windows, `/mnt/c`, sibling drives, or unrelated global installations when a required project command is unavailable.

For a host runtime, commands such as PHP, Composer, or Node must exist on that host. For a Docker Compose runtime, they must exist inside the configured application service. A failed preflight or required verification probe returns a nonzero result and identifies the exact runtime and missing command.

The agent must then ask the user whether to:

- install the command manually;
- start or rebuild the configured service;
- select a different Compose service;
- intentionally change the project runtime profile.

The harness never installs tools or changes images automatically.

## Verification results

Application verification writes `.harness/reports/last-verification.json` and reports:

- `PASS`: every required configured check ran and passed;
- `PASS_WITH_GAPS`: required checks passed, with visible optional gaps;
- `FAIL`: an executed check failed;
- `INCOMPLETE`: a required check or runtime command could not run.

Repository maintainers use `just validate` to validate AkiForge itself. It is
not a new-project command or proof that application checks passed.

## Codex compatibility

Codex uses `AGENTS.md`, generated `.codex/agents/*.toml`, compatible skills,
native command rules, and optional hooks. Activate the installed hooks only
through the preview/apply workflow in
[Codex configuration](https://github.com/niks0501/AkiForge/blob/main/docs/codex-configuration.md).

The PreToolUse hook contract remains intentionally narrow:

- return `{}` for unmatched, safe, and approval-required commands;
- return `permissionDecision: "deny"` only for forbidden commands or policy failures;
- let generated native Codex rules own approval prompts.

Do not introduce `permissionDecision: "ask"`, or a pass-through `allow` response without a valid input rewrite. Docker Compose and Laravel Sail wrappers are normalized before policy matching so wrapped migrations and dependency changes keep the same prompt requirements.

## OpenCode compatibility

OpenCode uses `AGENTS.md`, `opencode.jsonc`, and generated `.opencode/` adapters. Runtime detection and enforcement remain shared Python behavior rather than a platform-specific OpenCode hook.

OpenCode native permissions continue to handle `allow`, `ask`, and `deny`
decisions. Generated adapter files must not be edited directly; maintainers
change packaged canonical inputs, while projects regenerate through
`akiforge adapter generate`.

## Workflow routing

- Tiny: one or two local files, no API/schema/auth/deployment impact. Inspect, edit, run targeted verification, report.
- Normal: several related files or reversible behavior. Use a compact plan, implement, run targeted checks, review the diff, report.
- High risk: auth, permissions, secrets, uploads, payments, migrations, data deletion, deployment, production config, or broad architecture. Use full planning, relevant rules, independent review, full verification, and rollback notes.

Per-invocation approval remains required for dependency changes, Git publication/history operations, file deletion, migrations, deployments, credential access, production operations, and destructive data operations—even when wrapped by Docker or Sail.

## Context rules

Always loaded:

- `AGENTS.md`;
- the current request;
- the current role or workflow instructions.

Loaded only when relevant:

- `harness/rules/frontend.md`;
- `harness/rules/backend.md`;
- `harness/rules/security.md`;
- `harness/rules/database.md`;
- `harness/rules/deployment.md`;
- `harness/rules/testing.md`;
- `harness/rules/review.md`;
- project-specific architecture and API contracts.

Historical runs, completed tasks, all ADRs, and unrelated domain documentation stay unloaded by default.

## Legacy vendored compatibility

`just` recipes, direct `scripts/*.py` entry points, and full-project sync remain
available only for repositories that already vendor the old harness. They are
not the installation path for new projects. Do not prune vendored files during
the initial adoption change; prove verification and rollback first.

The exact mapping from every legacy command to the global CLI is in
[Command Migration](https://github.com/niks0501/AkiForge/blob/main/docs/command-migration.md). Unsupported legacy-only
maintenance commands are labeled there rather than silently redefined.
