ai-forge-cli 0.1.7__tar.gz → 2.0.0__tar.gz

{ai_forge_cli-0.1.7/src/ai_forge_cli.egg-info → ai_forge_cli-2.0.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: ai-forge-cli
-Version: 0.1.7
-Summary: Context walker for the Forge L0-L5 spec system
+Version: 2.0.0
+Summary: Context walker for the Forge spec system
 Requires-Python: >=3.11
 License-File: LICENSE
 Requires-Dist: pyyaml>=6.0

ai_forge_cli-2.0.0/README.md

@@ -0,0 +1,269 @@
+<div align="center">
+
+```
+███████╗ ██████╗ ██████╗  ██████╗ ███████╗
+██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝
+█████╗  ██║   ██║██████╔╝██║  ███╗█████╗  
+██╔══╝  ██║   ██║██╔══██╗██║   ██║██╔══╝  
+██║     ╚██████╔╝██║  ██║╚██████╔╝███████╗
+╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝
+```
+
+**Spec-driven agent development.**
+The agent drives the interview. The specs drive the code.
+
+[![CI](https://github.com/GreyFlames07/forge/actions/workflows/ci.yml/badge.svg)](https://github.com/GreyFlames07/forge/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+</div>
+
+---
+
+## What it is
+
+A hierarchical YAML spec system, a Python CLI for context assembly, and **six agent skills** that take a human from a vague product idea to working, reviewed, and validated code — with the agent asking questions and the human answering, not the reverse.
+
+Built on the premise that **people explain systems well under questioning but poorly when cold-prompted**. Forge inverts the default "human prompts agent → agent implements" loop into "agent interviews human → structured spec emerges → agent implements from spec".
+
+Runs in **Claude Code** and any **agentskills.io-compatible client** (VS Code Copilot, Cursor).
+
+---
+
+## The pipeline
+
+```
+  idea
+    ↓
+  forge-design    →  system design      (conception, systems, domains, modules, environments)
+    ↓
+  forge-spec      →  element specs      (elements, properties, operations, types, contracts, flows)
+    ↓
+  forge-cast      →  repo hydration     (existing codebase → draft Forge spec + uncertainty report)
+    ↓
+  forge-review    →  quality + security (completeness, consistency, contract correctness, attack vectors)
+    ↓
+  forge-build     →  code + tests       (parallel subagents, each element gets forge context)
+    ↓
+  forge-validate  →  validation report  (static analysis, test coverage, behavioral probes)
+    ↓
+  working system
+```
+
+Each skill is a SKILL.md directive (agent-facing) plus a shared `docs/framework-reference.md` (human reference). Agents use the `forge` CLI to load element context — no spec content is inlined in prompts.
+
+---
+
+## Install
+
+### Fresh machine — four commands
+
+```bash
+git clone https://github.com/GreyFlames07/forge.git
+cd forge
+uv venv --python 3.13 .venv && uv pip install -e . pytest
+./scripts/install-skills.sh install
+```
+
+This wires the `forge` binary into `~/.local/bin/` and symlinks the six skills into `~/.claude/skills/` and `~/.agents/skills/` — discoverable by every supported client.
+
+### Verify
+
+```
+forge --version           # shows installed forge version
+forge --help              # shows: init, update, context, list, inspect, find, validate, graph
+.venv/bin/pytest          # 74 passed
+```
+
+### Requirements
+
+| | |
+|---|---|
+| Python | ≥ 3.13 |
+| Package manager | [`uv`](https://docs.astral.sh/uv/) recommended; pip works |
+| Agent client | Claude Code or an agentskills.io-compatible client |
+
+If `forge: command not found`: add `~/.local/bin` to PATH.
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"  # add to ~/.zshrc to persist
+```
+
+---
+
+## Quick start
+
+Bootstrap a new project in any empty directory:
+
+```bash
+mkdir ~/my-idea && cd ~/my-idea
+forge init
+```
+
+```
+    ▸ Forge init in /Users/you/my-idea
+
+      ✓ spec/
+      ✓ spec/framework.yaml  (framework vocabulary)
+      ✓ spec/conception.yaml  (fill in your conception details)
+
+    ───── Next steps ─────
+
+      Edit spec/conception.yaml and replace placeholders:
+        id:  <conception>
+        name: <ConceptionName>
+
+      Create your first system directory:
+        mkdir -p spec/<system>
+        touch spec/<system>/system.yaml
+
+      Set the spec dir (add to shell rc to persist):
+        export FORGE_SPEC_DIR="/Users/you/my-idea/spec"
+
+      Validate at any time:
+        forge validate
+```
+
+Open an agent session in that directory and describe your idea. The relevant skill activates; the interview begins.
+
+---
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `forge init` | Scaffold a new project (`spec/` + `framework.yaml` + `conception.yaml`) |
+| `forge update` | Refresh `framework.yaml` to the current Forge version |
+| `forge --version` | Print the installed Forge CLI version |
+| `forge list [--kind K]` | Enumerate nodes in the spec dir |
+| `forge inspect <id>` | Lightweight metadata probe |
+| `forge context <element-id>` | Full implementation-ready bundle for an element |
+| `forge find <query>` | Substring search across IDs and descriptions |
+| `forge validate` | Lint the spec for structural and referential errors |
+| `forge graph` | Visualise the dependency graph |
+
+Spec-dir resolution order: `--spec-dir` flag > `$FORGE_SPEC_DIR` env var > auto-discover (walks upward looking for `spec/conception.yaml`).
+
+---
+
+## The six skills
+
+| Skill | Role | Input | Output |
+|---|---|---|---|
+| **forge-design** | System designer / interviewer | Vague product idea | conception.yaml, system.yaml, domain.yaml files, module.yaml skeletons, workbench/discovery.md |
+| **forge-spec** | Element elicitation | One module | Elements, properties, operations, types, errors, contracts, interactions, flows, datastores |
+| **forge-cast** | Codebase hydration | Existing non-Forge codebase | Draft Forge spec corpus anchored to repository evidence, workbench/cast-report.md |
+| **forge-review** | Quality + security review | Completed module specs | Completeness, consistency, contract correctness, attack vector analysis, workbench/review.md |
+| **forge-build** | Implementation orchestrator | Reviewed spec corpus | Code + tests dispatched via parallel subagents, each using `forge context <id>` |
+| **forge-validate** | Post-implementation validator | Implemented system + spec | Static analysis, test coverage, behavioral probes, workbench/validation.md |
+
+Skills activate via natural-language prompts (universal) or slash-commands (Claude Code only).
+
+---
+
+## The spec system
+
+Hierarchical YAML — one file per node, IDs derived from file paths.
+
+| Level | Node type | File location |
+|---|---|---|
+| Conception | conception | `spec/conception.yaml` |
+| System | system | `spec/<system>/system.yaml` |
+| Domain | domain | `spec/<system>/<domain>/domain.yaml` |
+| Module | module | `spec/<system>/<domain>/<module>/module.yaml` |
+| Element | element | `spec/<system>/<domain>/<module>/<element>.yaml` |
+| Registry | type, error, policy, contract, integration, interaction, flow | `spec/<system>/<registry>/` |
+| Implementation | datastore, environment, test, deployment | `spec/<system>/implementation/` |
+
+Process artifacts (discovery notes, review reports, build plans) live in `spec/<system>/workbench/`.
+
+Full schema reference: [`docs/framework-reference.md`](docs/framework-reference.md).
+
+---
+
+## Repository layout
+
+```
+forge/
+├── src/
+│   └── cli/              Python CLI package (the forge command)
+├── .agents/skills/       The 6 forge skills
+│   ├── forge-design/
+│   ├── forge-spec/
+│   ├── forge-cast/
+│   ├── forge-review/
+│   ├── forge-build/
+│   └── forge-validate/
+├── docs/
+│   └── framework-reference.md  Combined schema + enum + rule reference
+├── example/
+│   └── spec/             Working example spec (LinkHub URL shortener)
+├── scripts/
+│   └── install-skills.sh Global skill install + CLI symlink
+├── tests/                pytest suite — 74 tests
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## Development
+
+### Testing
+
+```bash
+.venv/bin/pytest -v
+```
+
+The `example/spec/` directory is a complete working spec (LinkHub, a URL shortener) that doubles as the test fixture and a reference for what a finished project looks like.
+
+```bash
+export FORGE_SPEC_DIR="$(pwd)/example/spec"
+forge list                                                    # see all nodes
+forge context linkhub.shortener.links.link_manager.short_link # full element bundle
+forge find redirect                                            # search across nodes
+forge validate                                                 # lint the spec
+```
+
+### Adding a new skill
+
+1. Create `.agents/skills/<name>/SKILL.md` with agentskills.io frontmatter (`name`, `description`).
+2. Symlink `references/framework.md` → `../../../../docs/framework-reference.md` for framework access.
+3. Add the skill to `SKILLS=()` in `scripts/install-skills.sh`.
+4. `./scripts/install-skills.sh install` to wire up globally.
+
+### Uninstall
+
+```bash
+./scripts/install-skills.sh uninstall
+```
+
+Removes all global skill symlinks and the `forge` CLI binary. Does not touch project `spec/` directories.
+
+---
+
+## Contributing
+
+Pull requests welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for:
+
+- Branching and commit conventions (Conventional Commits)
+- Local dev setup
+- PR requirements and CI expectations
+- Release process
+
+Changes are tracked in [`CHANGELOG.md`](CHANGELOG.md) following [Keep a Changelog](https://keepachangelog.com).
+
+## Security
+
+Security issues: see [`SECURITY.md`](SECURITY.md). Do not open public issues for vulnerabilities.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+---
+
+<div align="center">
+
+<sub>Built for agent-driven development. Questions over prompts. Specs over intentions. Code follows.</sub>
+
+</div>

{ai_forge_cli-0.1.7 → ai_forge_cli-2.0.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-forge-cli"
-version = "0.1.7"
-description = "Context walker for the Forge L0-L5 spec system"
+version = "2.0.0"
+description = "Context walker for the Forge spec system"
 requires-python = ">=3.11"
 dependencies = ["pyyaml>=6.0"]
 
@@ -16,6 +16,9 @@ forge = "cli.forge:main"
 where = ["src"]
 include = ["cli*"]
 
+[tool.setuptools.package-data]
+cli = ["framework.yaml"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]

{ai_forge_cli-0.1.7 → ai_forge_cli-2.0.0/src/ai_forge_cli.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: ai-forge-cli
-Version: 0.1.7
-Summary: Context walker for the Forge L0-L5 spec system
+Version: 2.0.0
+Summary: Context walker for the Forge spec system
 Requires-Python: >=3.11
 License-File: LICENSE
 Requires-Dist: pyyaml>=6.0

{ai_forge_cli-0.1.7 → ai_forge_cli-2.0.0}/src/ai_forge_cli.egg-info/SOURCES.txt

@@ -12,16 +12,19 @@ src/cli/__main__.py
 src/cli/bundle.py
 src/cli/common.py
 src/cli/forge.py
+src/cli/framework.yaml
 src/cli/index.py
 src/cli/walker.py
 src/cli/commands/__init__.py
 src/cli/commands/base.py
 src/cli/commands/context.py
 src/cli/commands/find.py
+src/cli/commands/graph.py
 src/cli/commands/init.py
 src/cli/commands/inspect.py
 src/cli/commands/list_cmd.py
 src/cli/commands/update.py
+src/cli/commands/validate.py
 tests/test_cli.py
 tests/test_find.py
 tests/test_index.py

ai_forge_cli-2.0.0/src/cli/__init__.py

@@ -0,0 +1,2 @@
+"""Forge CLI — context walker for the Forge spec system."""
+__version__ = "0.1.8"

{ai_forge_cli-0.1.7 → ai_forge_cli-2.0.0}/src/cli/bundle.py

@@ -13,30 +13,17 @@ import yaml
 
 # Human-readable headers for each bundle section.
 _SECTION_HEADERS: dict[str, str] = {
-    "target":                     "Target",
-    "l0_registry_slice":          "L0 — Registry (sliced)",
-    "l1_conventions":             "L1 — Conventions",
-    "l2_module":                  "L2 — Owner Module",
-    "l2_entry_points":            "L2 — Invoking Entry Points",
-    "policies_applied":           "L2 — Policies Applied",
-    "policies":                   "L2 — Policies",
-    "shared_module_interfaces":   "L2 — Whitelisted Module Interfaces",
-    "l3_atom":                    "L3 — Target Atom",
-    "l3_artifact":                "L3 — Target Artifact",
-    "owned_atoms":                "L3 — Owned Atoms",
-    "owned_artifacts":            "L3 — Owned Artifacts",
-    "called_atom_signatures":     "L3 — Called Atom Signatures",
-    "producer_atom_signature":    "L3 — Producer Atom Signature",
-    "source_artifacts":           "L3 — Upstream Source Artifacts",
-    "consumer_signatures":        "L3 — Consumer Signatures",
-    "training_artifact":          "L3 — Training Artifact",
-    "handler_atoms":              "L3 — Handler Atoms",
-    "step_atom_signatures":       "L3 — Step Atom Signatures",
-    "l4_journey":                 "L4 — Target Journey",
-    "l4_orchestration":           "L4 — Target Orchestration",
-    "invoked_orchestrations":     "L4 — Invoked Orchestrations",
-    "l4_callers":                 "L4 — Callers (atoms consumed here)",
-    "l5_operations":              "L5 — Operations",
+    "target":           "Target",
+    "element":          "Element",
+    "module":           "Module",
+    "domain":           "Domain",
+    "system":           "System",
+    "contracts":        "Contracts",
+    "types":            "Types",
+    "errors":           "Errors",
+    "interactions":     "Interactions",
+    "policies_applied": "Policies Applied",
+    "datastores":       "Datastores",
 }
 
 
@@ -60,11 +47,11 @@ def _render_yaml(bundle: OrderedDict[str, Any]) -> str:
     parts: list[str] = []
     target = bundle.get("target") or {}
     parts.append("# " + "=" * 66)
-    parts.append(f"# FORGE CONTEXT BUNDLE")
+    parts.append("# FORGE CONTEXT BUNDLE")
     parts.append(f"# target: {target.get('id', '<unknown>')}")
     parts.append(f"# kind:   {target.get('kind', '<unknown>')}")
-    if target.get("atom_kind"):
-        parts.append(f"# atom_kind: {target['atom_kind']}")
+    if target.get("element_kind"):
+        parts.append(f"# element_kind: {target['element_kind']}")
     parts.append("# " + "=" * 66)
     parts.append("")
 
@@ -91,8 +78,8 @@ def _render_markdown(bundle: OrderedDict[str, Any]) -> str:
         "",
         f"- **kind**: `{target.get('kind', '<unknown>')}`",
     ]
-    if target.get("atom_kind"):
-        parts.append(f"- **atom_kind**: `{target['atom_kind']}`")
+    if target.get("element_kind"):
+        parts.append(f"- **element_kind**: `{target['element_kind']}`")
     parts.append("")
 
     for key, value in bundle.items():

{ai_forge_cli-0.1.7 → ai_forge_cli-2.0.0}/src/cli/commands/__init__.py

@@ -13,10 +13,12 @@ builds its subparser, and wires dispatch via `args.handler`.
 
 from cli.commands import context as _context
 from cli.commands import find as _find
+from cli.commands import graph as _graph
 from cli.commands import init as _init
 from cli.commands import inspect as _inspect
 from cli.commands import list_cmd as _list_cmd
 from cli.commands import update as _update
+from cli.commands import validate as _validate
 
 ALL_COMMANDS = [
     _init,
@@ -25,4 +27,6 @@ ALL_COMMANDS = [
     _list_cmd,
     _inspect,
     _find,
+    _validate,
+    _graph,
 ]

{ai_forge_cli-0.1.7 → ai_forge_cli-2.0.0}/src/cli/commands/context.py

@@ -11,13 +11,12 @@ from cli import index as index_mod
 from cli import walker
 
 NAME = "context"
-HELP = "Build a full implementation-ready context bundle for an id."
+HELP = "Build a full implementation-ready context bundle for an element."
 DESCRIPTION = (
-    "Walks the spec dependency graph from <id> and emits everything "
-    "an agent needs to implement it: the target spec, referenced L0 "
-    "entries (sliced, not the whole registry), the owning module, "
-    "applicable policies, L1 conventions, L4 callers with derived "
-    "implications, and L5 operations."
+    "Walks the spec dependency graph from <element-id> and emits everything "
+    "an agent needs to implement it: the element (with inline properties and "
+    "operations), parent module/domain/system, referenced contracts, types "
+    "(transitive), errors, interactions, cascaded policies, and datastores."
 )
 
 
@@ -25,7 +24,7 @@ def register(sub: argparse._SubParsersAction) -> None:
     p = sub.add_parser(NAME, help=HELP, description=DESCRIPTION)
     p.add_argument(
         "id",
-        help="Target id. Must be an atom, module, journey, flow, or artifact.",
+        help="Target element id (e.g. myapp.billing.payments.charge_processor.charge).",
     )
     common.add_spec_dir_arg(p)
     p.add_argument(

{ai_forge_cli-0.1.7 → ai_forge_cli-2.0.0}/src/cli/commands/find.py

@@ -1,9 +1,8 @@
 """`forge find <query>` — substring search across entity IDs and descriptions.
 
 Used as the scanning primitive for reuse-before-create probes in the
-forge-discover and forge-decompose skills. Agents call this before writing
-a new module / atom / type / error to surface potential matches, then
-present them advisorily to the human.
+forge-spec skill. Agents call this before writing a new type or error
+to surface potential matches, then present them advisorily to the human.
 """
 
 from __future__ import annotations