Project ALEN

Project ALEN is a model-independent VS Code workbench for describing application architecture, generating project scaffolds, reviewing existing repositories, planning targeted code changes, and running local build/test workflows, and starting backend/frontend development services with live logs.

Generated source code is a starting point. Project ALEN validates structure and runs configured checks, but a successful generation or CI run is not a guarantee of production readiness.

Scaffold versus implementation

The Preview scaffold action creates deterministic templates. To generate actual application behavior, configure and test an AI provider, add meaningful project requirements and endpoint logic to the architecture, approve the model, then select Implement code with AI. Review the generated file plan before writing it to the workspace, then run Build and test. AI output is not guaranteed correct; compile, test, review security, and verify all business rules before use. If the requirements do not describe business behavior, the model may need to make assumptions; specify entities, validation, authorization, persistence, and error behavior for better results.

Getting started

1. Open a project folder in VS Code.
2. Press Ctrl+Shift+P (Cmd+Shift+P on macOS) and run Project ALEN: Open Workbench. Project ALEN: Open in Browser opens the same workbench in your browser.
3. Configure an AI provider on the AI connections page if you want AI-assisted proposal, review and code features. Provider keys are stored using VS Code SecretStorage.

Diagnostic log

Each project keeps a log of the session in .ai-architect/logs/ai-architect-log.txt, ignored by git: RPC calls, every AI request and reply with its model, tokens and time, agent and engine events, and errors with stack traces. Secrets are removed, and prompts and replies appear as redacted excerpts. Change the detail or turn it off on the Activity page, or open it with Project ALEN: Open Diagnostic Log.

Reviewed build-repair workflow

1. Run Build and test on selected generated components.
2. For failures, inspect Analyse failures with AI; diagnosis is advisory and not a verified fix.
3. Choose Prepare reviewed repair draft to carry a bounded failure summary into Repository intelligence. The workspace is rescanned locally first.
4. Select up to three eligible source files, review the goal, and draft changes. Selected source and diagnostic context are sent to the configured provider after best-effort redaction.
5. Inspect every before/after diff, apply only after explicit approval, then run Build and test again. The workflow does not automatically apply patches or claim success without test output.

Main features

• Architecture workbench: one validated model for components and dependency edges; schema-driven configuration, per-API details, an editable canvas, and architecture proposal review.
• Model providers: OpenAI, Anthropic, Gemini, and OpenAI-compatible endpoints; model discovery; capability/context-aware candidate filtering; cost-aware ranking where pricing is configured; bounded requests/retries; per-provider output limits; usage accounting; and exact-request cache keys.
• Repository intelligence: bounded metadata-only indexing of supported source/config files; import and symbol extraction; TODO and selected risky-pattern findings; AI-assisted review and change planning; choose up to a small number of files for a proposed patch; inspect a before/after diff; explicitly apply or discard it.
• AI context minimization: secret-like files are excluded from repository scans; common key/token/password patterns are redacted before repository review, follow-up, and diagnosis requests. Redaction is best-effort and does not guarantee that arbitrary secrets are detected. Review what you send to external providers.
• Project generation: Spring Boot (Maven/Gradle), Express, FastAPI, React/Vite, SQL/CQL specifications, OpenAPI 3.1 JSON contracts, Mermaid architecture diagrams, an initial ADR, Dockerfiles, Compose configuration, hardened Helm charts with optional HPA/PDB/Ingress, generated documentation, and security baseline guidance.
• Generated engineering automation: .editorconfig, GitHub Actions build/test workflows for built-in runnable templates, Dependabot configuration, and a dependency-review workflow for projects that include application code.
• Workspace and execution safeguards: path validation, symlink-aware checks, collision checks, explicit confirmation for writes and builds, Workspace Trust gates for operations that modify files or execute project commands, allowlisted build commands, bounded process time/output, and rollback attempts for multi-file writes.
• Integrations: PostgreSQL, MySQL, SQL Server, MongoDB, Cassandra, Redis, Kafka, RabbitMQ, Azure, and Git connection checks. Reachability checks do not always prove that credentials, permissions, or application-level operations work.

Built-in generators and current boundaries

GENERATION-NOTES.md records which components are runnable templates versus specification-only output. Do not treat a generated SPEC.md or an HTTP 501 route as a completed implementation.

Security and privacy notes

• Open the workspace only when you trust its contents. Build/test commands execute project code and may download dependencies.
• Do not supply production credentials to an AI agent. Generated CI runs with restricted token permissions and should not receive deployment secrets for untrusted pull requests.
• Secrets are redacted from common patterns before some AI review/diagnosis prompts, but no pattern-based redactor is complete. Avoid sharing credentials or confidential repository content with external providers.
• Repository scans index metadata, symbols, imports and findings rather than sending all source files. Source content is sent only for explicitly selected files during a change-drafting action, after a warning and user selection.
• Review every AI-generated diff before applying it. Generated files, manifests, SQL, container definitions, and workflow changes can have security impact.
• Keep credentials in the deployment environment’s secret manager. Never commit .env, private keys, API keys, or production configuration.
• Review and customize SECURITY-BASELINE.md for the specific application. The checklist is guidance, not a completed security certification.

Before production use

1. Build and test each generated service and frontend in a clean environment.
2. Implement business logic and meaningful success/failure tests.
3. Configure authentication, authorization, rate limits, CORS, logging, tracing and health/readiness checks.
4. Review dependency audit, image, infrastructure and secret-scanning results.
5. Review generated permissions/workflows and retain an SBOM for released artifacts.
6. Review every change and verify rollback/restore procedures.

Command line (CI and git hooks)

The same checks the workbench runs are available without VS Code and without AI:

node bin/ai-architect.js check --fail-on high   # rules, requirements readiness, scorecard of ai-architect.model.json
node bin/ai-architect.js scan --json            # repository index summary and risky-pattern findings
node bin/ai-architect.js methods                # RPC methods with their permission and audit level

check exits 1 when a finding is at or above --fail-on (high, medium, low, none) and 2 for usage or model errors, so it can gate a CI job. The model file is written by the workbench when Store the architecture in the repository is on; pass --model for another file. The CLI writes nothing into the repository; its state lives in ~/.ai-architect (or $AI_ARCHITECT_HOME).

Version

This is version 0.8.1. See CHANGELOG.md for the changes in each release.

AI providers, agent mode and activity panel

• Sign in instead of pasting keys: on AI connections choose GitHub Copilot (sign in with VS Code), OpenRouter (sign in with OAuth), Azure OpenAI (sign in with Microsoft), Google Gemini (sign in with Google) (needs your own Desktop OAuth client) or Custom endpoint (OAuth 2.0 sign-in). API-key providers work as before. Tokens live in VS Code SecretStorage; OAuth uses PKCE with a loopback redirect on 127.0.0.1.
• Pick the model per action: every AI button has a provider/model picker; "Default" follows the picker on AI connections, "Automatic" uses routing.
• Agent mode (default): the AI plans, reads files, edits them one at a time, builds where allowed and fixes its own errors. In the Repository and Fix-with-AI flows it can read the selected files and other non-secret files inside the same component folders (not the whole repository). Every change is still staged for your review; nothing is written until you apply it.
• Agent terminal: in a trusted workspace every agent has a run_command tool (git status, ls, running existing tests…). Commands run with the workspace (or a folder in it) as working directory; commands whose paths leave the workspace, that reach for the home directory or environment variables, or that act on the system or remote services (sudo, git push, publish, global installs, download-and-run) are refused. Credential-like environment variables are removed and output is redacted before the AI sees it; every command is echoed to the Build output log. This is a guard, not an OS sandbox: programs a command starts (tests, build scripts) run with your user's rights. The agent's staged edits are not on disk, so commands see the files as they are; staged changes are tested with Build & auto-fix.
• Usage limits left come from provider rate-limit headers, the OpenRouter credit balance and monthly budgets you set per provider. Providers that do not report limits (Gemini, Copilot) say so.
• AI activity panel: docked at the bottom while an AI operation runs, with sections side by side: thinking, todos, subagents and their progress, processes, steps, files, tokens and limits, project memory, a terminal, and the log. Long content is clipped.
• Requirements readiness and flow map: a local check (no AI) scores how complete the requirements are and lists every gap with a Fix button; the Flow map shows which screen calls which API and which API uses which tables, caches, queues and services, in both directions.
• Database schema designer: design tables, keys, relations and indexes visually or with AI, then save schema.sql / schema.mongodb.js / schema.cql into the project. The generators use the same schema.
• Full-screen review: click a changed file to see a side-by-side diff and accept or reject it.
• Project memory: agents keep short facts about the project (build commands, layout, conventions, pitfalls) in .ai-architect/memory.json and read them at the start of every task to save exploration requests. Manage it in the activity panel's Memory section.

Review, safety and integrations

• Undo: every applied draft and every write of generated files is a checkpoint; Undo AI changes restores the files (stored in .ai-architect/checkpoints/, last 50).
• Change blocks and second look: accept or reject each block of a draft; a cheaper model reviews drafts (AI connections → Second look). Applying drafts can be set to apply small low-risk drafts or all drafts automatically.
• Agent terminal: Workspace guard (default), or a Docker sandbox with or without network (needs Docker).
• Private folders: content from these folders only goes to local models (base URL on localhost, e.g. Ollama).
• Team rules: agents follow .ai-architect/rules.md, AGENTS.md, .github/copilot-instructions.md and CLAUDE.md.
• MCP: configure servers on AI connections (name: command args); agents get an mcp tool. To let other agents read your architecture, register node <extension>/src/mcp-server.js (working directory = your workspace) and turn on Store the architecture in the repository.
• Git: after applying a draft, Commit to a new branch or Commit and open pull request (needs gh).
• Preview deploy: Run & Logs → Preview deploy (Azure Container Apps through az containerapp up; creates billable resources).
• Model test bench: compare models on the same small service; nothing is written to the workspace.
• New stacks: Go (Gin), .NET (ASP.NET Core minimal API), GraphQL (Apollo Server), Vue, Next.js. Go and .NET need their SDKs installed to build and run.

Unreleased additions

• Typed APIs: in each API, list requestFields / responseFields as name:type[:required] lines (types: string int long number bool date datetime uuid email url object enum(a|b), a model name, or any of these with []). Shared entities go in the service's Data models field as Name(field:type[:required], ...).
• Regeneration keeps your edits: changed files are merged with the new scaffold (needs Git on PATH). conflict files are skipped until you Resolve or tick them.
• Run the whole system: docker compose up -d starts infrastructure; docker compose --profile apps up --build adds every service and the frontend. In Run & Logs, Start everything does the same with local processes and runs a smoke test.
• Import architecture from code (Repository page), Check architecture rules (Architecture review), and Security scan (Run & Logs) run locally without AI.
• Errors stay visible: error alerts in the top-right corner stay until you close them. AI request logs appear in the AI progress log.
• npm run test:vscode downloads VS Code and runs the integration test; npm run check stays offline.

AI workflows (v0.7.0)

• Propose architecture extracts every endpoint you list in the description into the owning service's API list (method, path, parameters, bodies, validation, logic) and shows them before you accept.
• Complete with AI (Requirements, or the component drawer) fills missing fields, designs the API list and answers open questions directly in the model. One click undoes it.
• AI architecture review returns findings with concrete configuration fixes; apply one or all.
• Implement code with AI runs a pipeline per component: plan files → write them in batches (new files such as DTOs, services, repositories, pages are allowed inside the component folder) → optionally build and test in a temporary folder and feed failures back for up to 3 rounds. A report shows what changed, assumptions, and whether the build passed. Click any file to compare it with the workspace before writing.
• Fix with AI (Run & Logs) picks the relevant files from failed components and drafts a reviewed repair diff; nothing is written until you apply it.

Scaffolds

• Spring Boot / Express / FastAPI scaffolds are layered (controller or route → service → in-memory store, plus error mapping). Unimplemented operations return HTTP 501 from the service layer.
• The React scaffold is generated from the connected services' API definitions: a typed API client, an API explorer screen that calls every operation, live service health on the overview, and a Vite dev proxy per service (/api/<service>), so no CORS setup is needed in development. Page screens are placeholders until implemented with AI.

Run & Logs

Build and test, start/stop backends and frontends, and follow output in log viewers with level colouring, filtering, follow mode, copy and clear. Python projects use a per-component .venv; dependencies must be installed with Build and test before starting Node projects.