agentic-development-framework 0.1.0__py3-none-any.whl

agentic_development_framework-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: agentic-development-framework
+Version: 0.1.0
+Summary: A local-first framework for agentic software development workflows.
+Project-URL: Homepage, https://github.com/Badsha-ugv/ide-agentic-development-framework
+Project-URL: Repository, https://github.com/Badsha-ugv/ide-agentic-development-framework
+Project-URL: Issues, https://github.com/Badsha-ugv/ide-agentic-development-framework/issues
+Project-URL: Changelog, https://github.com/Badsha-ugv/ide-agentic-development-framework/blob/main/CHANGELOG.md
+Author: Agentic Development Framework contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT 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: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=5.0; extra == 'dev'
+Requires-Dist: pytest<9,>=8.0; extra == 'dev'
+Requires-Dist: ruff<1,>=0.8; extra == 'dev'
+Requires-Dist: twine<7,>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Agentic Development Framework
+
+Agentic Development Framework (ADF) is a local-first foundation for persistent,
+human-controlled software development workflows driven through IDE coding agents.
+
+The project is being delivered incrementally. The current implementation provides the
+installable package, strict configuration validation, structured logging, safe project
+initialization, immutable requirements versioning, SQLite workflow state, recovery checkpoints,
+lifecycle commands, and Codex/Antigravity project configuration.
+
+## Requirements
+
+- Python 3.11 or newer
+
+## Installation
+
+Install the latest released version from PyPI:
+
+```bash
+python -m pip install agentic-development-framework
+adt --help
+```
+
+## Development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+pytest
+```
+
+## CLI
+
+Both entry points expose the same application:
+
+```bash
+adt --help
+python -m agentic_framework --help
+adt --version
+adt init
+adt config validate path/to/config.yaml
+adt requirements ingest
+adt start
+adt status
+adt pause
+adt resume
+adt continue
+adt stop
+adt review
+adt approve requirements_review
+adt revise requirements_review "Clarify the acceptance criteria"
+adt tasks
+```
+
+The validation command prints the normalized configuration as YAML and exits with code 2
+for missing, malformed, or invalid configuration.
+
+## Project initialization
+
+Run `adt init` or `python -m agentic_framework init` from the project directory. Initialization:
+
+- detects new and existing projects, common technologies, package managers, and parent Git roots;
+- creates the ADF runtime, requirements, documentation, and IDE discovery directories;
+- installs initial configuration and project guidance without replacing existing files;
+- writes proposed content under `.agentic/proposals/` when a generated file conflicts; and
+- initializes Git only when no repository is already present.
+
+Use `--path DIRECTORY` to target another directory or `--no-git` to suppress Git initialization.
+The operation is idempotent. Its latest report is written to
+`.agentic/reports/initialization.md`.
+
+## Requirements management
+
+Add one or more source files below `requirements/inbox/`, including files in nested folders,
+then run:
+
+```bash
+adt requirements ingest
+```
+
+Each changed submission creates the next directory under `requirements/versions/`. The version
+contains byte-for-byte source copies, SHA-256 hashes, a manifest, consolidated extracted text, a
+requirement index, and initial traceability records. Existing versions are hash-validated before
+use and are never updated. An unchanged inbox is reported as a duplicate without creating a new
+version.
+
+Starting with the second version, ADF compares source files and `REQ-NNN` requirement blocks and
+writes an impact report under `requirements/reports/`. Added, modified, removed, and unchanged
+items are reported separately, along with documentation, architecture, implementation, testing,
+and approval review prompts.
+
+Markdown, text, CSV, TSV, JSON, YAML, and reStructuredText are extracted as UTF-8 text. Other
+formats—including PDF, DOCX, XLSX, and images—are still preserved exactly and recorded with a
+clear unsupported-extraction status. Optional binary-format extractors are future work.
+
+See `docs/REQUIREMENTS_MANAGEMENT.md` for the file contract and safety behavior.
+
+## Runtime state and recovery
+
+Initialization creates `.agentic/database/agentic.db` as the transactional source of truth,
+inspection snapshots under `.agentic/state/`, a JSONL event history, and checkpoint storage.
+Pause and stop persist checkpoints. Resume verifies checkpoint integrity and restores the
+checkpoint stage instead of trusting potentially inconsistent conversational context or snapshot
+files. Mandatory workflow approval stages cannot advance until approval is recorded.
+
+## IDE configuration
+
+ADF generates root `AGENTS.md`, a shared command skill under
+`.agents/skills/agentic-commands/`, and Antigravity rules under `.agents/rules/`. The Codex adapter
+uses the documented root instructions and repository-local skill surfaces. The `.codex/agents/`
+directory contains an informational compatibility note; ADF does not claim an undocumented
+custom-agent file format is automatically discovered.
+
+## Configuration
+
+ADF configuration uses YAML and rejects unknown keys to catch mistakes early:
+
+```yaml
+schema_version: 1
+project:
+  name: example-project
+  mode: auto
+runtime:
+  directory: .agentic
+  log_level: INFO
+ide:
+  enabled:
+    - codex
+policies:
+  allow_network: false
+  allow_destructive_operations: false
+```
+
+Runtime directories must be project-relative and cannot contain parent-directory traversal.
+
+## Logging
+
+`configure_logging()` sets up readable console output and can additionally write a JSONL
+event stream. Reconfiguration is idempotent and only replaces handlers managed by ADF.
+
+See `docs/IMPLEMENTATION_PLAN.md` and `docs/IMPLEMENTATION_PROGRESS.md` for scope and status. The
+maintainer release procedure is documented in `docs/PYPI_RELEASE.md`.

agentic_development_framework-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+agentic_framework/__init__.py,sha256=8tbFK-7k7l988vwMRe2eSeonngS3Bv9effHprI9jfW4,112
+agentic_framework/__main__.py,sha256=fHn8AFsz1H4xtmbMVsTaBxC9PNr96qqd8aocXjUsVuQ,140
+agentic_framework/cli.py,sha256=RAW4tJV3GNeZptUf3J8ngptkYdWaBdxOhS6ys3C_IUM,8418
+agentic_framework/exceptions.py,sha256=C8bMuXkRaYr3sXXbsMOZcPrwiglDm8myZ4f6W7x7lrQ,610
+agentic_framework/logging.py,sha256=mHa65Qt-KdA6XsjcnM0RYbCyaxGrvGNt3FB9sexOXJU,2247
+agentic_framework/adapters/__init__.py,sha256=1vR3_hu_F6m0YSFBPTvme16p-98IZYv743xm9EalGy8,176
+agentic_framework/adapters/generator.py,sha256=zRx-psapXDmSfMKow0fW7RoAVpxelc_rbvQycbmzKp8,4805
+agentic_framework/core/__init__.py,sha256=-n3tAT8X8Smg8FcQghm9kMHh_3Ck_Z9LnFhA7tAVXZQ,32
+agentic_framework/core/command_registry.py,sha256=_DQiianO0HhVCnoXgxikH60x0T2DazcoIypgRKedqUc,708
+agentic_framework/core/config.py,sha256=sLs_-NbjwOXgT5OFtGKczKLpVEfmQoisuJeN1SK5t4g,4425
+agentic_framework/core/initialization.py,sha256=TaC4hfaM-I4ybqjIKpV_BsO3wRVk31mtXxyjyv6PfkA,7995
+agentic_framework/core/project.py,sha256=MVVmxepUFlF4PL7tfOwk7uae0ddti-s8OJL1AbxS9Dg,2827
+agentic_framework/core/workflow.py,sha256=5xDolQDbGC3kO5shkCtWE3WTzCdP_iRKDz43a6VJiw4,3976
+agentic_framework/requirements_manager/__init__.py,sha256=Q1T1sIh9n2VxbBucCg_RNzZ6hYgYVJHWZdGe6ccC02M,234
+agentic_framework/requirements_manager/comparison.py,sha256=04Yxd-eK1EST1tbt-ps8wKlULHjhmS2OgwsLGWnXnR8,4807
+agentic_framework/requirements_manager/extraction.py,sha256=SSRbc6W4VDSS7jpnirCfFU2lVuyVCwPWCLoc50dhLvE,1362
+agentic_framework/requirements_manager/ingestion.py,sha256=iYRIXB8HQt15KHl05mjVXoN2nWpp-9_rx5wYfWAkMlI,14947
+agentic_framework/requirements_manager/traceability.py,sha256=azvdk3rc8Uq_gknNn3H9KMg7cUP0q13ltG56f8gq6LE,2254
+agentic_framework/state/__init__.py,sha256=w4no5X4gzvJr935HcZvszZscATGSkEepsMBbBKzQQu8,135
+agentic_framework/state/database.py,sha256=P_XZgLovy7NZTMx39K32_s_jfGjaZDUZcSsCR0Lj2aU,9060
+agentic_framework/templates/__init__.py,sha256=D1B-_zlAKldwEbDY_kEvAfltg6OLZOuLyt4b5Ujgtdw,42
+agentic_framework/templates/skills/agentic-commands/SKILL.md,sha256=dRTAY5eUCZ4hC-K-m49_nVAUybdkkiG_4N0XvGE-FHE,1052
+agentic_development_framework-0.1.0.dist-info/METADATA,sha256=mDEQN5wWOGzgaxPI0XuIjVprvv7PQGPNqQODJK4_XGY,6491
+agentic_development_framework-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+agentic_development_framework-0.1.0.dist-info/entry_points.txt,sha256=yLrtkLPdApbQjlyVZYNpmRtgc0prbjpJGwF3G9td_zk,50
+agentic_development_framework-0.1.0.dist-info/licenses/LICENSE,sha256=6BzOzZ1c-kyBOz_uNhWQKM1xPmPEQzSNwubTqgniGM0,1100
+agentic_development_framework-0.1.0.dist-info/RECORD,,

agentic_development_framework-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentic_development_framework-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+adt = agentic_framework.cli:app

agentic_development_framework-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Agentic Development Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

agentic_framework/__init__.py

@@ -0,0 +1,6 @@
+"""Agentic Development Framework public package metadata."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]
+

agentic_framework/__main__.py

@@ -0,0 +1,7 @@
+"""Module entry point for ``python -m agentic_framework``."""
+
+from agentic_framework.cli import app
+
+if __name__ == "__main__":
+    app()
+

agentic_framework/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""IDE adapter assets generated from canonical definitions."""
+
+from agentic_framework.adapters.generator import generated_project_files
+
+__all__ = ["generated_project_files"]

agentic_framework/adapters/generator.py

@@ -0,0 +1,139 @@
+"""Canonical workflow, agent, policy, and IDE adapter assets."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+
+import yaml
+
+STAGES = (
+    "project_initialization",
+    "project_discovery",
+    "requirements_ingestion",
+    "requirements_analysis",
+    "srs_and_project_documentation",
+    "requirements_review",
+    "system_architecture",
+    "architecture_review",
+    "ui_ux_design",
+    "design_review",
+    "development_planning",
+    "implementation",
+    "integration",
+    "qa_and_testing",
+    "code_and_security_review",
+    "docker_and_ci_cd_validation",
+    "final_documentation",
+    "release_review",
+    "completed",
+)
+
+APPROVAL_STAGES = {
+    "requirements_review",
+    "architecture_review",
+    "design_review",
+    "release_review",
+}
+
+_AGENTS = (
+    ("main_orchestrator", "Main Orchestrator"),
+    ("requirements_analyst", "Requirements Analyst"),
+    ("software_architect", "Software Architect"),
+    ("ui_ux_designer", "UI/UX Designer"),
+    ("frontend_developer", "Frontend Developer"),
+    ("backend_developer", "Backend Developer"),
+    ("integration_engineer", "Integration Engineer"),
+    ("qa_engineer", "QA Engineer"),
+    ("code_reviewer", "Code Reviewer"),
+    ("security_reviewer", "Security Reviewer"),
+    ("devops_engineer", "DevOps Engineer"),
+)
+
+_RULES = """# Agentic Development Framework rules
+
+Read the root `AGENTS.md` and `.agentic/config.yaml` before framework work. Interpret `/start`,
+`/status`, `/pause`, `/resume`, `/continue`, `/stop`, `/review`, `/approve`, `/revise`,
+`/requirements`, and `/tasks` as ADF workflow commands. Use `adt <command>` to persist state.
+Never bypass approval gates or overwrite unrelated project changes.
+"""
+
+_CODEX_NOTE = """# Codex adapter
+
+Codex discovers the root `AGENTS.md` and `.agents/skills/agentic-commands/SKILL.md`. Canonical
+specialist roles live in `.agentic/agent-registry.yaml`. This directory is informational because
+ADF does not assume an undocumented filesystem format for Codex custom agents.
+"""
+
+
+def _yaml(value: object) -> str:
+    return yaml.safe_dump(value, sort_keys=False)
+
+
+def _workflow() -> str:
+    stages = []
+    for index, stage_id in enumerate(STAGES):
+        stages.append(
+            {
+                "id": stage_id,
+                "purpose": stage_id.replace("_", " ").title(),
+                "required_inputs": [],
+                "agent": "main_orchestrator",
+                "expected_outputs": [],
+                "dependencies": [STAGES[index - 1]] if index else [],
+                "validation_rules": ["required checks pass"],
+                "approval_required": stage_id in APPROVAL_STAGES,
+                "failure_behavior": "stop and preserve recoverable state",
+                "retry_policy": {"max_attempts": 3},
+                "checkpoint_policy": "on_completion",
+            }
+        )
+    return _yaml({"schema_version": 1, "name": "default", "stages": stages})
+
+
+def _registry() -> str:
+    agents = []
+    for agent_id, name in _AGENTS:
+        agents.append(
+            {
+                "id": agent_id,
+                "name": name,
+                "role": name,
+                "responsibilities": [f"Perform {name.lower()} work within approved scope"],
+                "scope": "assigned tasks only",
+                "required_inputs": [],
+                "expected_outputs": ["standardized agent result"],
+                "allowed_tools": ["repository read/write tools", "project test commands"],
+                "restricted_operations": ["secrets", "force push", "unapproved deployment"],
+                "verification_requirements": ["run relevant checks"],
+                "handoff_format": "agent result contract",
+                "failure_and_escalation": "record blocker and escalate to orchestrator",
+            }
+        )
+    return _yaml({"schema_version": 1, "agents": agents})
+
+
+def generated_project_files() -> dict[str, str]:
+    """Return deterministic canonical assets for project initialization."""
+
+    skill = (
+        files("agentic_framework")
+        .joinpath("templates/skills/agentic-commands/SKILL.md")
+        .read_text(encoding="utf-8")
+    )
+    return {
+        ".agentic/workflow.yaml": _workflow(),
+        ".agentic/policies.yaml": _yaml(
+            {
+                "schema_version": 1,
+                "filesystem": "project_only",
+                "destructive_operations": "require_explicit_approval",
+                "network": "deny_by_default",
+                "deployment": "require_approval",
+                "secrets": "never_expose_or_commit",
+            }
+        ),
+        ".agentic/agent-registry.yaml": _registry(),
+        ".agents/rules/adf.md": _RULES,
+        ".agents/skills/agentic-commands/SKILL.md": skill,
+        ".codex/agents/README.md": _CODEX_NOTE,
+    }

agentic_framework/cli.py

@@ -0,0 +1,264 @@
+"""Command-line interface for the Agentic Development Framework."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from agentic_framework import __version__
+from agentic_framework.core.command_registry import COMMANDS
+from agentic_framework.core.config import dump_config, load_config
+from agentic_framework.core.initialization import FileStatus, initialize_project
+from agentic_framework.core.workflow import WorkflowService
+from agentic_framework.exceptions import (
+    ConfigurationError,
+    InitializationError,
+    RequirementsError,
+    StateError,
+)
+from agentic_framework.requirements_manager import RequirementsManager
+
+app = typer.Typer(
+    name="adt",
+    help="Local-first agentic development workflow tooling.",
+    no_args_is_help=True,
+)
+config_app = typer.Typer(help="Inspect and validate framework configuration.")
+requirements_app = typer.Typer(
+    help="Show, version, and compare project requirements.", invoke_without_command=True
+)
+app.add_typer(config_app, name="config")
+app.add_typer(requirements_app, name="requirements")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"adt {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool | None,
+        typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version."),
+    ] = None,
+) -> None:
+    """Run Agentic Development Framework commands."""
+
+
+@app.command("init")
+def init_project(
+    path: Annotated[
+        Path,
+        typer.Option("--path", help="Project directory to initialize."),
+    ] = Path("."),
+    initialize_git: Annotated[
+        bool,
+        typer.Option("--git/--no-git", help="Initialize Git when no repository is detected."),
+    ] = True,
+) -> None:
+    """Safely initialize ADF in a new or existing project."""
+
+    try:
+        result = initialize_project(path, initialize_git=initialize_git)
+    except InitializationError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+
+    created = sum(item.status is FileStatus.CREATED for item in result.files)
+    typer.echo(f"Initialized {result.inspection.root}")
+    typer.echo(f"Project mode: {result.mode.value}")
+    typer.echo(f"Created files: {created}")
+    typer.echo(f"Conflicts: {len(result.conflicts)}")
+    typer.echo("Report: .agentic/reports/initialization.md")
+
+
+def _workflow_action(path: Path, action: str) -> None:
+    try:
+        service = WorkflowService(path)
+        result = getattr(service, action)()
+    except StateError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+    typer.echo(f"Status: {result['status']}")
+    typer.echo(f"Stage: {result['current_stage']}")
+
+
+@app.command("start")
+def start(path: Annotated[Path, typer.Option("--path")] = Path(".")) -> None:
+    """Start the persisted workflow."""
+
+    _workflow_action(path, "start")
+
+
+@app.command("status")
+def status(path: Annotated[Path, typer.Option("--path")] = Path(".")) -> None:
+    """Show persisted workflow status."""
+
+    _workflow_action(path, "status")
+
+
+@app.command("pause")
+def pause(path: Annotated[Path, typer.Option("--path")] = Path(".")) -> None:
+    """Pause safely and create a checkpoint."""
+
+    _workflow_action(path, "pause")
+
+
+@app.command("resume")
+def resume(path: Annotated[Path, typer.Option("--path")] = Path(".")) -> None:
+    """Validate the latest checkpoint and resume."""
+
+    _workflow_action(path, "resume")
+
+
+@app.command("continue")
+def continue_command(path: Annotated[Path, typer.Option("--path")] = Path(".")) -> None:
+    """Advance to the next eligible workflow stage."""
+
+    _workflow_action(path, "continue_workflow")
+
+
+@app.command("stop")
+def stop(path: Annotated[Path, typer.Option("--path")] = Path(".")) -> None:
+    """Stop safely and create a checkpoint."""
+
+    _workflow_action(path, "stop")
+
+
+@app.command("help")
+def help_command() -> None:
+    """List conversational and CLI framework commands."""
+
+    for name, description in COMMANDS.items():
+        typer.echo(f"/{name}: {description}")
+
+
+@app.command("tasks")
+def tasks(path: Annotated[Path, typer.Option("--path")] = Path(".")) -> None:
+    """List persisted workflow tasks."""
+
+    try:
+        values = WorkflowService(path).store.tasks()
+    except StateError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+    if not values:
+        typer.echo("No tasks recorded.")
+    for task in values:
+        typer.echo(f"{task['task_id']} [{task['status']}] {task['title']}")
+
+
+@app.command("review")
+def review(path: Annotated[Path, typer.Option("--path")] = Path(".")) -> None:
+    """List items awaiting approval or revision."""
+
+    try:
+        values = WorkflowService(path).store.approvals()
+    except StateError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+    pending = [item for item in values if item["status"] != "approved"]
+    if not pending:
+        typer.echo("No deliverables waiting for review.")
+    for item in pending:
+        typer.echo(f"{item['stage_id']}: {item['status']}")
+
+
+@app.command("approve")
+def approve(
+    stage: Annotated[str, typer.Argument(help="Workflow stage ID to approve.")],
+    path: Annotated[Path, typer.Option("--path")] = Path("."),
+) -> None:
+    """Record explicit approval for a stage."""
+
+    try:
+        service = WorkflowService(path)
+        service.approve(stage)
+    except StateError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+    typer.echo(f"Approved: {stage}")
+
+
+@app.command("revise")
+def revise(
+    stage: Annotated[str, typer.Argument(help="Workflow stage ID to revise.")],
+    feedback: Annotated[str, typer.Argument(help="Revision feedback.")],
+    path: Annotated[Path, typer.Option("--path")] = Path("."),
+) -> None:
+    """Record revision feedback for a stage."""
+
+    try:
+        service = WorkflowService(path)
+        service.revise(stage, feedback)
+    except StateError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+    typer.echo(f"Revision requested: {stage}")
+
+
+@config_app.command("validate")
+def validate_config(
+    path: Annotated[
+        Path,
+        typer.Argument(help="YAML configuration file to validate.", exists=False),
+    ],
+) -> None:
+    """Validate a YAML configuration file and print its normalized representation."""
+
+    try:
+        config = load_config(path)
+    except ConfigurationError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+    typer.echo(dump_config(config), nl=False)
+
+
+@requirements_app.callback()
+def requirements_status(
+    context: typer.Context,
+    path: Annotated[Path, typer.Option("--path", help="Project directory.")] = Path("."),
+) -> None:
+    """Show the latest requirements version when no subcommand is supplied."""
+
+    if context.invoked_subcommand is not None:
+        return
+    try:
+        latest = RequirementsManager(path).latest_version()
+    except RequirementsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+    if latest is None:
+        typer.echo("No requirements version has been published.")
+    else:
+        typer.echo(f"Current requirements: {latest['version']}")
+        typer.echo(f"Source files: {len(latest['files'])}")
+
+
+@requirements_app.command("ingest")
+def ingest_requirements(
+    path: Annotated[
+        Path,
+        typer.Option("--path", help="Project directory containing requirements/inbox."),
+    ] = Path("."),
+) -> None:
+    """Preserve and publish all files currently in the requirements inbox."""
+
+    try:
+        result = RequirementsManager(path).ingest()
+    except RequirementsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+    if result.duplicate:
+        typer.echo(f"No changes; inbox matches {result.version}.")
+        return
+    typer.echo(f"Created {result.version} from {result.file_count} source file(s).")
+    typer.echo(f"Requirement IDs: {result.requirement_count}")
+    if result.impact_report:
+        relative_report = result.impact_report.relative_to(result.version_path.parents[1])
+        typer.echo(f"Impact report: {relative_report}")
+

agentic_framework/core/__init__.py

@@ -0,0 +1,2 @@
+"""Core framework services."""
+

agentic_framework/core/command_registry.py

@@ -0,0 +1,16 @@
+"""Central registry for chat and CLI command compatibility."""
+
+COMMANDS = {
+    "start": "Start or initialize the project workflow",
+    "status": "Display persisted workflow status",
+    "pause": "Pause safely and create a checkpoint",
+    "resume": "Validate recovery state and resume",
+    "continue": "Advance to the next eligible workflow stage",
+    "stop": "Stop safely and create a checkpoint",
+    "help": "Show available framework commands",
+    "review": "Show deliverables waiting for approval",
+    "approve": "Approve a workflow stage",
+    "revise": "Record revision feedback for a stage",
+    "requirements": "Show the latest requirements version",
+    "tasks": "Display persisted tasks",
+}