From bbc5fb0b037b6c9f6f354262f590d4bb071bb207 Mon Sep 17 00:00:00 2001 From: Nilotpal Saha Date: Wed, 6 May 2026 17:10:29 +0530 Subject: [PATCH] docs: expand project README --- README.md | 370 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 369 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1f8eabb..07d995c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,371 @@ # Autonomous Dev System -Initial scaffold for AI-driven Figma → Code → PR pipeline. \ No newline at end of file +Autonomous Dev System is an early-stage scaffold for an AI-assisted **Figma → Code → Pull Request** pipeline. The repository models a multi-agent software delivery flow where planner, database, API, UI, QA, validation, review, and GitHub automation components can collaborate to turn a feature request into generated artifacts, quality-gate decisions, and pull-request automation. + +> **Project status:** scaffold/prototype. Most modules currently return deterministic placeholder output and are intended to be extended with real model providers, repository indexing, Figma ingestion, code generation, CI execution, and GitHub write operations. + +## Table of Contents + +- [Basic Introduction](#basic-introduction) +- [Prerequisites](#prerequisites) +- [Getting Started](#getting-started) +- [Architecture Overview](#architecture-overview) +- [Repository Structure](#repository-structure) +- [Features and Status](#features-and-status) +- [Configuration](#configuration) +- [Testing Guide](#testing-guide) +- [Development Workflow](#development-workflow) +- [CI/CD](#cicd) +- [Roadmap](#roadmap) +- [Contributing](#contributing) +- [Troubleshooting](#troubleshooting) + +## Basic Introduction + +The project explores how AI agents can coordinate the implementation lifecycle for product features: + +1. Accept a feature request or design-driven task. +2. Break the request into implementation work. +3. Generate database, API, and UI artifacts. +4. Extract and validate contracts between generated layers. +5. Generate tests from contracts. +6. Run quality gates and AI review checks. +7. Feed failures back into a self-healing loop. +8. Optionally create or merge GitHub pull requests. + +The current codebase is intentionally lightweight. It provides module boundaries and orchestration patterns rather than production-ready generation logic. + +## Prerequisites + +### Required + +- **Python 3.10+** — GitHub Actions currently configures Python 3.10. +- **Git** — for cloning, branching, committing, and pull-request workflows. +- **pip** and optionally **venv** — for local dependency installation. + +### Optional, depending on which modules you run + +Some prototype modules import optional third-party libraries that are not yet captured in a requirements file: + +- **pytest** — for local test discovery and CI parity. +- **requests** — required by GitHub service modules. +- **numpy**, **faiss** or **faiss-cpu**, and **sentence-transformers** — required by the embedding/vector-store based context engine. +- A model provider SDK/API key — needed when replacing placeholder agents with real LLM calls. +- A GitHub token with appropriate repository permissions — needed for GitHub branch, file, PR, or merge automation. + +## Getting Started + +### 1. Clone the repository + +```bash +git clone +cd figma-code-gen-pr +``` + +### 2. Create and activate a virtual environment + +```bash +python -m venv .venv +source .venv/bin/activate +``` + +On Windows PowerShell: + +```powershell +python -m venv .venv +.\.venv\Scripts\Activate.ps1 +``` + +### 3. Install local dependencies + +There is no committed `requirements.txt` yet. For the currently wired CI path, install pytest: + +```bash +python -m pip install --upgrade pip +python -m pip install pytest +``` + +If you plan to use GitHub service helpers or the vector context engine, install the optional dependencies you need: + +```bash +python -m pip install requests numpy sentence-transformers faiss-cpu +``` + +### 4. Run a basic orchestrator smoke test + +```bash +python - <<'PY' +from ai.workflows.contract_orchestrator import run_feature + +result = run_feature("Create a signup form") +print(result) +PY +``` + +### 5. Run validation and test-generation flow + +```bash +python - <<'PY' +from ai.workflows.contract_orchestrator import run_feature +from ai.workflows.validation_orchestrator import validate_and_generate_tests + +result = run_feature("Create a signup form") +validation = validate_and_generate_tests( + result["schema"], + result["api_contracts"], + result["ui_contracts"], +) +print(validation) +PY +``` + +## Architecture Overview + +The system is organized as layered orchestration around specialized agents: + +```text +Feature request / design task + │ + ▼ +Planner / Sprint manager + │ + ▼ +DB Agent ──► Schema Extractor + │ │ + ▼ ▼ +API Contract Generator ──► API Agent + │ │ + ▼ ▼ +UI Contract Generator ──► UI Agent + │ + ▼ +Contract Validator + Test Generator + │ + ▼ +Gate Orchestrator + LLM Judge + │ + ├── pass ──► GitHub PR / merge services + │ + └── fail ──► QA self-healing feedback loop +``` + +### Key layers + +- **Agents (`ai/agents`)**: Specialized generators and reviewers for planning, DB, API, UI, development, and QA feedback. +- **Contracts (`ai/contracts`)**: Converts generated database schema information into API contracts and UI bindings. +- **Workflows (`ai/workflows`)**: Coordinates agent execution for single-feature, dependency-aware, contract-aware, validation, and self-healing flows. +- **Agile orchestration (`ai/agile`)**: Adds sprint/backlog decomposition, quality gates, retry loops, and merge decisions. +- **Context (`ai/context`)**: Provides repository-awareness scaffolding with a naive in-memory engine and a vector-store-based variant. +- **Validation and testing (`ai/validation`, `ai/testing`)**: Checks cross-layer contract consistency and emits generated test skeletons. +- **Review and observability (`ai/review`, `ai/observability`)**: Provides placeholder LLM scoring and event logging. +- **GitHub services (`ai/services`)**: Contains helper classes for GitHub branch, file, PR, and merge API operations. +- **CI (`.github/workflows`)**: Runs pull-request validation scaffolding. + +## Repository Structure + +```text +. +├── .github/workflows/ +│ ├── ai_pipeline.yml # Pull-request AI validation scaffold +│ └── ci.yml # Basic pull-request CI scaffold +├── ai/ +│ ├── agents/ # Planner, developer, DB, API, UI, and QA agents +│ ├── agile/ # Sprint, pipeline, and quality-gate orchestration +│ ├── context/ # Repo context/RAG and vector-store prototypes +│ ├── contracts/ # Schema, API contract, and UI contract generators +│ ├── observability/ # Event monitoring helper +│ ├── prompts/ # Prompt templates +│ ├── review/ # LLM judge placeholder +│ ├── services/ # GitHub automation helpers +│ ├── testing/ # Test-generation helper +│ ├── validation/ # Contract validation logic +│ └── workflows/ # End-to-end and focused workflow orchestrators +└── README.md +``` + +## Features and Status + +| Feature | Status | Notes | +| --- | --- | --- | +| Multi-agent module layout | In progress | Core agent boundaries exist for planner, DB, API, UI, developer, and QA roles. | +| Figma-to-code pipeline | Planned | The repository describes the pipeline goal, but Figma API ingestion and design parsing are not implemented yet. | +| Planner agent | Prototype | Returns a simple one-task plan. | +| DB generation | Prototype | Returns placeholder SQL text for a task. | +| API generation | Prototype | Returns placeholder API code for a task. | +| UI generation | Prototype | Returns placeholder UI code for a task. | +| Contract-aware orchestration | Prototype | Coordinates DB, schema extraction, API contracts, UI contracts, and generated artifacts. | +| Schema extraction | Prototype | Parses simple SQL-like `CREATE TABLE` output. | +| API contract generation | Prototype | Builds basic POST endpoint contracts from extracted schema tables. | +| UI contract generation | Prototype | Builds form bindings from API contracts. | +| Contract validation | Prototype | Checks API fields against schema and UI fields against API contracts. | +| Test generation | Prototype | Emits API/UI test skeleton strings from contracts. | +| Quality gates | Prototype | Provides contract, test, and placeholder LLM-judge gates. | +| Self-healing QA loop | Prototype | Converts failures into fix prompts for a developer agent placeholder. | +| Repository context engine | Prototype | Includes naive in-memory search and a vector-store variant. | +| LLM judge | Placeholder | Returns a fixed score until connected to a real model provider. | +| GitHub PR automation | Prototype | Contains GitHub API helper methods; production encoding, error handling, and authentication flow need hardening. | +| GitHub auto-merge | Prototype | Contains a merge helper; should be guarded by policy, checks, and permissions before production use. | +| Observability | Prototype | Prints structured event dictionaries with UTC timestamps. | +| CI workflow | Scaffolded | Pull-request workflows exist; AI gate currently echoes a success message. | +| Dependency management | Planned | A pinned dependency file is not yet present. | +| Unit/integration tests | Planned | No committed test suite is present yet. | + +Legend: + +- **Planned**: Intended capability with little or no implementation. +- **Placeholder**: Stub behavior that returns fixed or deterministic mock data. +- **Prototype**: Minimal implementation useful for local experimentation but not production hardened. +- **In progress**: Foundational implementation exists and is expected to evolve. + +## Configuration + +The scaffold currently avoids hard-coding runtime configuration. As production integrations are added, prefer environment variables and local `.env` files that are excluded from Git. + +Suggested future environment variables: + +| Variable | Purpose | +| --- | --- | +| `GITHUB_TOKEN` | Authenticate GitHub API branch, file, PR, and merge operations. | +| `GITHUB_REPOSITORY` | Target repository in `owner/name` format. | +| `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or provider-specific keys | Authenticate model calls for generation, review, and self-healing loops. | +| `FIGMA_TOKEN` | Authenticate Figma API reads when Figma ingestion is implemented. | +| `FIGMA_FILE_KEY` | Identify the Figma source file for design-to-code runs. | +| `VECTOR_INDEX_PATH` | Persist or load local vector indexes when context storage is expanded. | + +## Testing Guide + +### Run all tests + +```bash +pytest +``` + +At the moment, the repository does not include committed test files, so pytest may report that no tests were collected. This is expected until a test suite is added. + +### Run Python syntax checks + +```bash +python -m compileall ai +``` + +This verifies that the Python modules can be parsed and byte-compiled in the current environment. + +### Run targeted smoke checks + +Contract-aware workflow: + +```bash +python - <<'PY' +from ai.workflows.contract_orchestrator import run_feature +print(run_feature("Create a todo list")) +PY +``` + +Validation workflow: + +```bash +python - <<'PY' +from ai.workflows.validation_orchestrator import validate_and_generate_tests + +schema = {"users": ["email", "name"]} +api_contracts = [{"endpoint": "/users", "method": "POST", "request": ["email", "name"], "response": ["id", "email", "name"]}] +ui_contracts = [{"form": "/users", "fields": ["email", "name"], "submit_to": "/users"}] +print(validate_and_generate_tests(schema, api_contracts, ui_contracts)) +PY +``` + +Quality gate workflow: + +```bash +python - <<'PY' +from ai.agile.gate_orchestrator import GateOrchestrator + +validation = {"api_errors": [], "ui_errors": [], "api_tests": "test api", "ui_tests": "test ui"} +print(GateOrchestrator().decide(validation, artifacts={})) +PY +``` + +### Suggested future test coverage + +- Unit tests for schema extraction edge cases. +- Unit tests for API and UI contract generation. +- Contract validator success and failure cases. +- Generated-test format checks. +- Pipeline orchestrator retry and gate-decision behavior. +- GitHub service tests with mocked HTTP responses. +- Context engine search and vector-store behavior. + +## Development Workflow + +1. Create a branch for your change. +2. Update or add modules under the relevant `ai/` package. +3. Add or update tests for the behavior you changed. +4. Run `python -m compileall ai` and `pytest` locally. +5. Open a pull request. +6. Use the AI pipeline and CI results to review failures. +7. Iterate until quality gates pass. + +Recommended standards as the project matures: + +- Add type hints to public APIs. +- Keep agent interfaces small and explicit. +- Avoid side effects during imports. +- Add dependency pins before relying on third-party packages in CI. +- Mock external APIs in tests. +- Treat auto-merge as a protected operation requiring explicit policy gates. + +## CI/CD + +The repository includes two pull-request workflows: + +- **CI**: A minimal workflow that currently checks out the repository and prints a CI message. +- **AI Pipeline**: Installs Python 3.10 and pytest, runs pytest, and executes a placeholder AI gate check. + +These workflows should be expanded with dependency installation, linting, type checking, unit tests, integration tests, coverage reporting, generated-artifact validation, and real gate enforcement. + +## Roadmap + +Potential next steps: + +- Add `requirements.txt` or `pyproject.toml` with pinned dependencies. +- Add a first unit test suite. +- Implement real Figma file ingestion and node extraction. +- Replace placeholder agents with provider-backed model calls. +- Persist generated artifacts to a workspace before committing them. +- Harden GitHub API helpers with proper Base64 content encoding, response validation, retries, and typed errors. +- Add structured logging and trace IDs across orchestrators. +- Add policy controls for auto-merge and production repository writes. +- Add examples for common feature-generation scenarios. + +## Contributing + +Contributions should preserve the scaffold's clear separation between agents, contracts, workflows, gates, and services. When adding a production integration, include tests and document any required configuration. + +Before opening a pull request, run: + +```bash +python -m compileall ai +pytest +``` + +## Troubleshooting + +### `ModuleNotFoundError` for `requests`, `faiss`, `numpy`, or `sentence_transformers` + +Install only the optional dependencies required for the modules you are running. For example: + +```bash +python -m pip install requests numpy sentence-transformers faiss-cpu +``` + +### `pytest` reports no tests collected + +No test suite is currently committed. Use the smoke-test commands in this README until unit tests are added. + +### GitHub API calls fail + +Confirm that your token has the required repository permissions, that `repo` is passed in `owner/name` format, and that the target branch or pull request exists. + +### Vector context engine fails to initialize + +The vector engine depends on optional native and ML packages. Start with the simple `ContextEngine` if you only need in-memory text search, or install `faiss-cpu`, `numpy`, and `sentence-transformers` for `ContextEngineV2`.