# adf

**Repository Path**: lowkeydan/adf

## Basic Information

- **Project Name**: adf
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Development Framework

ADF v0.3 is local, transparent infrastructure for governed agentic development.
Codex performs intelligent work, read-only specialist subagents provide independent
review, Guardian v0.3.0 supplies deterministic evidence, and a Stop Hook enforces
the completion boundary.

> ADF should automate discipline, not automate complexity.
>
> The project remains the source of truth.

Guardian never calls AI, edits project files, approves business decisions, or
performs commit, push, or deploy actions.

## How work flows

```text
Natural-language request
→ adf-workflow Skill: classification, risk and Task Contract when needed
→ read-only exploration
→ Main Codex implementation
→ independent architecture/test/docs review by risk
→ project tests, typecheck, build and other deterministic verification
→ Guardian commit/push gates
→ project Delivery Policy plus current authorization
→ guardian complete archives the delivered lifecycle
→ Stop Hook completion interlock
```

L0/L1 tasks use a lighter path. L2 uses the full contract and review flow. L3
adds human approval for security, migrations, destructive or production actions.
Bugfixes always use Systemic Diagnosis before editing.

## Components

- `AGENTS.md`: stable collaboration and ownership boundaries.
- `.agents/skills/adf-workflow/`: the single workflow entry and detailed SOP.
- `.codex/agents/`: read-only Explorer and specialist Reviewer profiles.
- `guardian/`: Node.js 20+ deterministic CLI and reports.
- `.codex/hooks.json`: minimal Stop Hook; project-local hooks require Codex trust.
- `templates/new-project/`: installable project snapshot of the same capabilities.

## Build and verify

```powershell
npm --prefix guardian ci
npm --prefix guardian run typecheck
npm --prefix guardian test
npm --prefix guardian run build
node scripts/validate-release.mjs
```

Release validation also keeps the single `scripts/guardian.ps1` launcher
7-bit ASCII so Windows PowerShell 5.1 never depends on the host code page when
parsing it.

The repository has no assumed public remote. Clone URLs must come from the owner.
Set `AI_DEV_FRAMEWORK_ROOT` to the local clone so project hooks and launchers can
resolve the one built Guardian Core.

## Guardian commands

For a workflow-enabled L2 task, Codex first creates and aligns
`.adf/tasks/current.md`, then starts with explicit classification:

```text
guardian start
  --request "增加供应商管理功能"
  --modules "api,web"
  --paths "api/**,web/**,docs/**"
  --types "feature,api"
  --success "行为、测试、文档和构建完成"
  --task-type feature
  --risk L2
  --required-gate push
  --contract .adf/tasks/current.md
  --contract-approval approved

guardian check --phase focused

guardian check --phase commit
  --workflow-state VERIFYING
  --architecture-review "<independent findings result>"
  --test-review "<acceptance/regression result>"
  --docs-review "<authority consolidation result>"
  --doc-review "<documentation maintenance>"
  --semantic-review "<duplication/debt review>"

git add <intended-paths>
git commit -m "<task delivery>"
guardian check --phase push --workflow-state READY_TO_RELEASE ...
git push <remote> <feature-branch>
guardian complete --reason "任务已交付"
guardian interlock
```

`reportOnly: true` still records `wouldBlock` without changing check exit codes.
The Stop Hook therefore reads report freshness and findings, never just the CLI
exit code. An active Guardian session blocks normal completion; a bounded repeat
may only stop with an explicit blocker message. Only `guardian complete` archives
and clears the completed lifecycle, after the effective gate and required local
commit/push-tracking evidence are satisfied. Guardian never queries remote Git.

## New project

Copy every file under `templates/new-project/` into a new project, including
hidden `.adf`, `.agents`, `.codex`, and `.guardian` directories. Then ask Codex to
inspect the real project, replace template placeholders, configure project-owned
verification, and run `guardian doctor`. Existing projects must merge rather than
overwrite their facts.

See [new-project setup](docs/new-project-setup.md) and the template's
[START-HERE](templates/new-project/START-HERE.md).

## Current documentation

- [Current workflow](docs/current-workflow.md)
- [Guardian usage and config](docs/guardian-usage.md)
- [New-project setup and migration](docs/new-project-setup.md)
- [Development principles](docs/philosophy.md)
- [ADF v0.3 implementation report](docs/v0.3-implementation-report.md)
- [v0.2.1 implementation history](docs/v0.2.1-implementation-report.md)

Design-history documents remain background only and are not current operating
instructions.