experimental / learning project

DevForge CLI
AI governance lab.

A personal experiment in AI-assisted software governance.

DevForge CLI explores local-first briefs, handoffs, policy gates, human review, evidence packs, and PR guidance for AI-assisted development. It is not a finished product, not a compliance tool, and not a universal repository scanner.

$ pipx install git+https://github.com/mffdeo/devforge-ai-cli.git

The main lesson: deterministic heuristics are useful for signals, but not enough to understand arbitrary projects. The better shape is a governance harness.

devforge@lab: ~/experiment

$ devforge scan
[DevForge] Signals collected

project_type: python_cli
stack: Python
profile_status: draft
confidence: medium

Project profile is preliminary.
Recommended:
  devforge scan --agent codex
  devforge profile approve

$ devforge plan --spec specs/SPEC.md
domain: cli_session_history
prcp: Minimal
policy: ALLOW
required_evidence:
- test_report
- audit_log

Local
artifacts

Briefs
+ evidence

Reviewable
outputs

No built-in
cloud

Learning
project

The original idea

What I tried

I wanted a CLI that could sit between AI coding and pull request review: scan the repository, generate a plan, check policy, require evidence, and prepare merge guidance.

What changed

Real tests showed that the scanner should not pretend to understand every project. It should collect signals, create drafts, and ask for review.

What this is not

It is not a production compliance system, not a security guarantee, and not a substitute for human engineering judgment.

The workflow I wanted

init / scan

Collect deterministic signals and draft a Project Profile.

specify

Turn an idea into a SPEC with assumptions and gray areas.

plan / implement

Create briefs and optionally hand them to an external local agent.

policy / review

Check risk and record explicit human review when required.

evidence / pr-ready

Package evidence and generate commit and PR guidance.

What worked

Structured handoffs

SPECs, Plan Packs, Context Packs, Implementation Briefs, and Agent Instructions made the work easier to inspect.

Evidence Pack

Markdown and JSON evidence made policy state, test reports, human review, and audit logs visible before PR.

PR guidance

The `pr-ready` command clarified which files to commit, which files to avoid, and what PR body to use.

What broke

False positives

`input()`, `user`, and `session` can mean local CLI interaction, not personal data or authentication.

Negated scope

Text like "no database" or "sem banco" contains risky words while saying the opposite.

Universal scanning

The tests showed that deterministic heuristics should produce reviewable signals, not final truth.

What I learned

Deterministic scan is useful for raw signals, not complete understanding.
Project Profiles should be reviewed and approved by a human.
The strongest design is a local-first governance harness.
Agent-assisted reasoning should refine briefs and gray areas, not hide decisions.
Policy must stay proportional to the actual project and SPEC scope.

Read the longer write-up in LESSONS_LEARNED.md.

Current status

Experimental

The CLI is useful for learning and experimentation, but all outputs should be reviewed.

Local-first

Artifacts are written locally under `.devforge/`. No internal LLM or cloud service is called by default.

Not compliance

The project does not prove security, privacy, legal, or regulatory compliance.

Try it locally

Install from GitHub