agentic-sdlc

Deterministic local execution runtime for agentic software workflows.

This repository runs a single consolidated workflow engine with:

deterministic workflow execution and trace IDs
resumable runs with persisted state
idempotent step short-circuit support
runtime policy enforcement for permissions and trust tier
structured step telemetry and trace timeline export

Determinism Scope

Determinism currently applies to orchestration semantics:

ready-step ordering
state transitions and persistence
trace generation and replayability of engine decisions

LLM-generated text/content can still vary across runs unless provider/model/settings enforce deterministic output behavior. Treat content reproducibility as a separate concern from workflow engine determinism.

Current Release

Runtime target: v1.0.1
Package version: 1.0.1

Quick Start

cargo run -- --workflow valid_flow.md

Onboard/check local prerequisites:

./scripts/bootstrap.sh
cargo run -- workflow doctor
cargo run -- workflow setup

workflow setup now bootstraps a full core package when missing:

rules (runtime/branching/coding/merge)
workflows (starter/feature/bugfix/review/release)
templates (feature/bugfix/review/release_prompt)
roles (architect/implementer/reviewer/resolver/releaser)
starter skills (analyze_code/generate_tests/next_steps)

Run deterministic CI gate locally:

./scripts/ci_gate.sh

Optional live provider smoke tests (OpenAI/Gemini):

ANTIGRAV_RUN_LIVE_LLM_TESTS=1 OPENAI_API_KEY=... cargo test llm_subagent_live_smoke_openai -- --nocapture
ANTIGRAV_RUN_LIVE_LLM_TESTS=1 GEMINI_API_KEY=... cargo test llm_subagent_live_smoke_gemini -- --nocapture

Inspect active/previous runs:

cargo run -- workflow list
cargo run -- workflow status
cargo run -- workflow threads

Run a workflow with a reusable template prompt:

cargo run -- workflow start-template feature_prompt --task "add email validation to signup flow"

Run a role-bound workflow launch:

cargo run -- workflow start-role implementer --task "add email validation to signup flow"

Run chat-thread orchestration (thread branch + workflow + optional merge lifecycle):

cargo run -- workflow chat-thread feature-email --message "implement signup email validation"
cargo run -- workflow chat-thread review-thread --message "review current diff" --workflow-id review --template review_prompt --role reviewer --no-merge

Run thread-to-branch lifecycle end-to-end (includes auto conflict resolution attempts):

cargo run -- workflow thread-flow my-thread --target-branch main --validate-command "cargo test"

Run a direct workflow with template/role overrides:

cargo run -- --workflow-id feature --template feature_prompt --task "add email validation to signup flow"
cargo run -- --workflow-id feature --role-override "architect=planner,implementer=debugger"

Inspect available role profiles and templates:

cargo run -- workflow roles
cargo run -- workflow templates

Scaffold markdown package files with schema headers:

cargo run -- workflow scaffold workflow feature-search --profile advanced
cargo run -- workflow scaffold skill search_docs --profile advanced

Skill scaffold now follows folder layout:

.agents/skills/<skill-name>/SKILL.md

Generate an advanced domain pack (workflows + skills + roles + templates):

cargo run -- workflow scaffold-domain payments

Rebuild graph index for context retrieval (also refreshes sqlite context tables in .agents/memory/context.db):

cargo run -- workflow index-graph

Run skill quality validation and strict gate:

cargo run -- workflow quality-skills
cargo run -- workflow quality-skills --strict

List available curated bundles:

cargo run -- workflow bundles
cargo run -- workflow bundles --json

Hot domain bundles currently included:

ai-engineering
cloud-platform
cybersecurity
data-ml-eval
healthtech
climate-tech

Quick examples:

cargo run -- --workflow-id ai-engineering/feature --template ai-engineering/feature_prompt --task "build eval pipeline for support agent"
cargo run -- --workflow-id cybersecurity/review --template cybersecurity/review_prompt --task "review auth middleware diff for vulnerabilities"

Security Workflow and Internet Skill Gate

This repository now enforces a package rule:

workflows using internet-capable skills must include an explicit security-check step
recommended gate step is internet_security_check using cybersecurity.security_scan_guard

Run the dedicated security workflow:

cargo run -- --workflow-id cybersecurity/security-scan --template cybersecurity/security_scan_prompt --task "scan internet-surface risks and policy drift"

Run security/package validation gates:

cargo run -- workflow check
cargo run -- workflow quality-skills --strict

Run workflow report evaluation gate from dataset:

cargo run -- workflow eval .agents/evals/release_eval.json
cargo run -- workflow eval .agents/evals/release_eval.json --min-pass-rate 0.9 --json

Manual approval gate for release/review-sensitive runs:

cargo run -- workflow status <instance_id>
cargo run -- workflow approve <instance_id> --step manual_approval_gate --by release-manager --note "qa+security passed"
cargo run -- workflow resume <instance_id>

To explicitly block a run at the gate:

cargo run -- workflow reject <instance_id> --step manual_approval_gate --by security --note "critical risk unresolved"

Generate catalog/manifest/lock artifacts for skill bundles:

cargo run -- workflow build-catalog

Import third-party SKILL.md repos into local .agents/skills/imported:

cargo run -- workflow import-skills https://github.com/anthropics/skills --max-skills 20
cargo run -- workflow import-skills https://github.com/anthropics/skills --allow-missing-license
cargo run -- workflow import-skills https://github.com/anthropics/skills --mode global --allow-missing-license

Imported skills are normalized to folder layout:

.agents/skills/imported/<skill-name>/SKILL.md

Install using installer-style alias command:

cargo run -- workflow install-skillpack https://github.com/anthropics/skills --mode local --allow-missing-license
cargo run -- workflow install-skillpack https://github.com/anthropics/skills --mode global --allow-missing-license

Sync existing imported skills using pinned source commit/provenance from .agents/skills.lock.json:

cargo run -- workflow sync-imports --overwrite
cargo run -- workflow sync-imports --mode global --overwrite --allow-missing-license

Normalize existing imported skill metadata (risk/source/tags) without re-pulling upstream repos:

cargo run -- workflow normalize-imported-skills
cargo run -- workflow normalize-imported-skills --dry-run --json
cargo run -- workflow normalize-imported-skills --mode global --json

Install a curated bundle into local/global skills root:

cargo run -- workflow install-bundle core
cargo run -- workflow install-bundle imported --mode global --overwrite

Verify lock integrity (detect missing/changed/extra skill entries):

cargo run -- workflow verify-lock
cargo run -- workflow verify-lock --mode global --fail-on-extra
cargo run -- workflow verify-lock --require-attestation

--mode local writes to .agents/skills/imported; --mode global writes to $CODEX_HOME/skills/imported (fallback: ~/.codex/skills/imported).

cargo run -- workflow mcp-register ollama-cli --transport stdio --command npx --arg -y --arg mcp-client-for-ollama --arg --ollama-host --arg http://127.0.0.1:11434
cargo run -- workflow mcp-register local-supabase --transport http --url http://127.0.0.1:54321/mcp --allow-tool query --allow-tool list_tables
cargo run -- workflow mcp-list
cargo run -- workflow mcp-ping
cargo run -- workflow mcp-ping ollama-cli --timeout-ms 8000 --json
cargo run -- workflow mcp-policy local-supabase --tool query

Resume a run:

cargo run -- workflow resume <instance_id>

Export trace:

cargo run -- workflow trace <instance_id> --json
cargo run -- workflow trace <instance_id> --timeline
cargo run -- workflow trace <instance_id> --otel

LLM Router

llm_subagent now routes real provider calls with timeout/retry/fallback and normalized telemetry output.

Common environment variables:

ANTIGRAV_LLM_PROVIDER=ollama|openai|gemini|anthropic
ANTIGRAV_LLM_MODEL=<primary model>
ANTIGRAV_LLM_FALLBACK=openai,gemini,anthropic
ANTIGRAV_LLM_FALLBACK_POLICY=transient_only|always|never
ANTIGRAV_LLM_TIMEOUT_MS=30000
ANTIGRAV_LLM_MAX_RETRIES=2
ANTIGRAV_LLM_SIMULATION_FALLBACK=true
OPENAI_API_KEY=...
GEMINI_API_KEY=...
ANTHROPIC_API_KEY=...

Context retrieval service (for deterministic LLM context injection):

ANTIGRAV_CONTEXT_RETRIEVAL_MODE=vector|graph|hybrid|off
ANTIGRAV_CONTEXT_BACKEND=json|sqlite
ANTIGRAV_CONTEXT_INDEX_PATH=.agents/memory/vector_index.json
ANTIGRAV_CONTEXT_MIN_SCORE=0.1
ANTIGRAV_CONTEXT_GRAPH_INDEX_PATH=.agents/memory/graph_index.json
ANTIGRAV_CONTEXT_GRAPH_MIN_SCORE=0.05
ANTIGRAV_CONTEXT_DB_PATH=.agents/memory/context.db
ANTIGRAV_CONTEXT_VECTOR_TABLE=vector_entries
ANTIGRAV_CONTEXT_GRAPH_TABLE=graph_nodes
ANTIGRAV_CONTEXT_MAX_ITEMS=5
ANTIGRAV_CONTEXT_MAX_CHARS=300

Generated Artifacts

These files are generated and ignored by git by default:

.agents/catalog/*
.agents/skills_index.json
.agents/workflows.json
.agents/bundles.json
.agents/marketplace.json
.agents/skills.lock.json
.agents/skills/imported/*

Roadmap

Current gap closure plan is tracked in:

docs/GAP_ROADMAP.md

Regenerate them anytime with:

cargo run -- workflow build-catalog

Skill Format

Skill markdown supports both formats:

frontmatter metadata (--- block with at least name/domain/executor)
fenced JSON metadata block (existing format)

Folder-skill layout is supported:

.agents/skills/<skill-name>/SKILL.md
optional .agents/skills/<skill-name>/references/ and .agents/skills/<skill-name>/scripts/

Installation

cargo install --path .
antigrav workflow doctor

Documentation

Architecture and runtime semantics: docs/ARCHITECTURE.md
CLI usage guide: docs/CLI_USAGE.md
Dev OS execution blueprint: docs/DEV_OS_BLUEPRINT.md
Release notes: CHANGELOG.md
Agent package guide: .agents/README.md
Gemini package contract: .agents/GEMINI.md

Name	pm
Description	Project Manager role responsible for planning, scope management, and task allocation. Activate when starting a new project or sprint.

pm

SKILL.md