Initial Loop Engineer MVP

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,24 @@
+name: Bug report
+description: Report reproducible Loop Engineer behavior
+title: '[Bug]: '
+labels: [bug]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: Describe the observed and expected behavior without private repository content.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction
+      description: Include commands, OS, Node, Git and provider CLI versions. Remove secrets.
+    validations:
+      required: true
+  - type: textarea
+    id: security
+    attributes:
+      label: Security impact
+      description: Use private vulnerability reporting instead if disclosure could put users at risk.

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,25 @@
+name: Feature request
+description: Propose a scoped product or workflow change
+title: '[Feature]: '
+labels: [enhancement]
+body:
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use case
+      description: Name the user, task and current constraint.
+    validations:
+      required: true
+  - type: textarea
+    id: safety
+    attributes:
+      label: Permission and security impact
+      description: Explain any new filesystem, process, network or provider authority.
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+    validations:
+      required: true

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 5
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## Change
+
+Describe the user-visible behavior and scope.
+
+## Security and permissions
+
+List changes to provider flags, commands, filesystem access, redaction or trust boundaries.
+
+## Validation
+
+- [ ] `npm run lint`
+- [ ] `npm run typecheck`
+- [ ] `npm test`
+- [ ] `npm run test:coverage`
+- [ ] `npm run build`
+- [ ] No secrets or private provider output in the diff

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm test
+      - run: npm run test:coverage
+      - run: npm run build

.gitignore

@@ -0,0 +1,15 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+coverage/
+
+# Loop Engineer runtime data (runs, worktrees, caches) — never version these
+.loop-engineer/
+
+# OS / editor
+.DS_Store
+*.log
+.idea/
+.vscode/

.prettierignore

@@ -0,0 +1,6 @@
+dist/
+coverage/
+node_modules/
+package-lock.json
+CHANGELOG.md
+.loop-engineer/

.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "singleQuote": true,
+  "printWidth": 100,
+  "trailingComma": "all",
+  "semi": true
+}

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes will appear in this file. The project follows Keep a Changelog and plans to use Semantic Versioning after the first public release.
+
+## [Unreleased]
+
+### Added
+
+- Local-first Claude Code, Codex CLI and predefined-command providers.
+- Structured role handoffs, bounded correction loops and objective quality gates.
+- Detached Git worktrees, redacted run reports and safe cleanup.
+- `init`, `doctor`, `run`, `status`, `report` and `clean` commands.
+- `gui` command: local-only dashboard (loopback bind, CSRF token, strict CSP) to configure, start, watch and cancel runs.
+- Provider-signaled subscription/session limits are classified as "provider unavailable" (exit 3) instead of an internal error.

CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+We want contributors to work without harassment, intimidation or personal attacks.
+
+Treat technical disagreement as a chance to examine evidence. Respect names, pronouns, backgrounds and experience levels. Do not publish private information, sexual content, threats or sustained disruption.
+
+Maintainers may edit or remove comments, commits, issues and other contributions that violate these rules. They may issue a warning or temporary or permanent ban based on severity and history.
+
+Report conduct concerns through a private maintainer contact or GitHub's private reporting tools. Maintainers will limit details to people who need them to handle the report.

CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Open an issue before a broad workflow or security change. Describe the user problem, trust boundary and acceptance criteria.
+
+Create a focused branch, add tests first and run the full validation suite from [development notes](docs/development.md). Do not commit fixtures that contain provider output, access tokens, personal paths or private repository content.
+
+Pull requests should explain behavior changes, security impact and manual checks. Keep provider-specific flags inside adapters. Keep workflow policy inside the orchestrator and security modules.
+
+By participating, you agree to follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Botond Csereklye
+Copyright (c) 2026 Loop Engineer 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

README.md

@@ -0,0 +1,172 @@
+# Loop Engineer
+
+Assign Claude, Codex and local tools to different software-engineering roles and run a controlled development loop in an isolated Git worktree.
+
+Use your existing authenticated coding-agent CLIs. No API keys, cloud account or automatic push required.
+
+> [!WARNING]
+> Loop Engineer is an unofficial open-source project. It has no affiliation with OpenAI or Anthropic. Review agent output and the generated diff before you copy changes into your branch.
+
+## Problem
+
+Coding agents can edit quickly, but a long unstructured chat mixes planning, implementation and approval. It can also expose a repository to prompt injection or let a test command exceed the authority you intended to grant.
+
+Loop Engineer assigns one role per step. Each role receives a bounded prompt, a permission profile and a Zod-validated JSON handoff. Writing roles work in a detached Git worktree. The tester runs commands from an exact allowlist.
+
+## Workflow
+
+```text
+ANALYZE -> PLAN -> IMPLEMENT -> TEST -> REVIEW -> DECIDE
+                                  ^        |
+                                  |        v
+                                  +------ FIX
+```
+
+The orchestrator stops when tests and review gates pass, the cycle limit expires, runtime expires, progress stops, a provider fails, or the user cancels.
+
+## Installation
+
+Requirements: Node.js 20+, Git, and at least one supported official agent CLI.
+
+```bash
+git clone <your-fork-or-clone-url>
+cd loop-engineer
+npm install
+npm run build
+npm link
+```
+
+Loop Engineer uses the sessions managed by `claude` and `codex`. Sign in through those CLIs. Do not paste provider passwords or browser tokens into Loop Engineer.
+
+## 30-second quickstart
+
+Run these commands inside a Git repository with at least one commit:
+
+```bash
+loopeng init
+loopeng doctor
+loopeng gui
+```
+
+The dashboard opens at `http://127.0.0.1:4317`. Configure the task, role providers, models, quality gates and test commands, then start with a dry run. Loop Engineer does not commit or push.
+
+Prefer the terminal? Run `loopeng run --task "Add input validation to the settings parser"` instead.
+
+## Commands
+
+```text
+loopeng init
+loopeng doctor
+loopeng gui
+loopeng gui --no-open --port 4318
+loopeng run --task "Add password reset"
+loopeng run --task-file task.md
+loopeng run --config loop-engineer.yml --task "Fix the parser"
+loopeng run --dry-run --task "Preview this workflow"
+loopeng status
+loopeng report <run-id>
+loopeng clean [--force]
+```
+
+`gui` starts a local-only dashboard bound to `127.0.0.1`. It reads the same `loop-engineer.yml` as the CLI and keeps the role permission boundaries fixed. Stop it with `Ctrl+C`.
+
+`doctor` checks Node, Git, repository state, worktree support, provider installation, command detection, instruction files and write access. It reports an unknown authentication state when an official CLI offers no dependable probe.
+
+## Configuration
+
+`loopeng init` writes `loop-engineer.yml` and detects common build commands. Zod rejects unknown keys, invalid role permissions and unsafe tester assignments.
+
+```yaml
+version: 1
+project:
+  root: .
+  default_branch: main
+workflow:
+  name: feature-development
+  max_cycles: 3
+  max_runtime_minutes: 60
+  stop_on_no_progress: true
+  require_human_approval_before_apply: false
+roles:
+  analyst: { provider: codex, model: default, permissions: read-only }
+  planner: { provider: claude, model: default, permissions: read-only }
+  implementer: { provider: codex, model: default, permissions: workspace-write }
+  reviewer: { provider: claude, model: default, permissions: read-only }
+  tester: { provider: local, permissions: predefined-commands }
+  fixer: { provider: codex, model: default, permissions: workspace-write }
+  final_judge: { provider: claude, model: default, permissions: read-only }
+quality_gates:
+  require_tests_pass: true
+  require_clean_review: true
+  block_severities: [critical, high]
+commands:
+  install: ''
+  build: 'npm run build'
+  test: 'npm test'
+  lint: 'npm run lint'
+  typecheck: 'npm run typecheck'
+security:
+  network_access: false
+  allow_package_install: false
+  allow_commit: false
+  allow_push: false
+  redact_secrets: true
+```
+
+See [configuration](docs/configuration.md) for validation rules.
+
+## Roles and providers
+
+The MVP includes `analyst`, `planner`, `implementer`, `reviewer`, `tester`, `fixer` and `final_judge`. Claude Code and Codex CLI handle agent roles. The local provider runs test commands without a shell.
+
+Provider flags can change between CLI releases. Run `loopeng doctor` after you upgrade a provider. See [providers](docs/providers.md).
+
+## Security model
+
+- Repository text enters prompts inside untrusted-data fences.
+- Read-only roles receive read-only provider permissions.
+- Implementer and fixer receive workspace write access inside the isolated worktree.
+- The tester rejects shell chaining, pipes, redirection, command substitution and denied binaries.
+- Logs and reports redact common token, key and password patterns before storage.
+- Loop Engineer issues no commit, push, force reset or destructive clean command.
+
+Redaction catches common patterns, not every secret format. Run reports can contain sensitive source context. Keep `.loop-engineer/` local and review [the security model](docs/security.md).
+
+## Worktrees and reports
+
+Loop Engineer creates `.loop-engineer/worktrees/<run-id>` from the current commit. Existing modifications in your main checkout stay untouched. `clean` removes worktrees with Loop Engineer marker files and refuses dirty worktrees unless you pass `--force`.
+
+Each completed run writes Markdown and JSON under `.loop-engineer/runs/<run-id>/`, together with configuration, task, handoffs, provider events, tests and review results.
+
+## Limitations
+
+- The MVP supports Claude Code, Codex CLI and a local command runner.
+- Provider CLI output formats may change.
+- The context firewall and redactor reduce risk but cannot prove that a provider will behave safely.
+- Loop Engineer leaves the worktree for human inspection and does not apply its diff to your branch.
+- Windows support depends on Git worktree behavior and provider CLI support on the host.
+
+## Roadmap
+
+Planned work includes Gemini support, optional MCP integration, richer progress evidence and opt-in packaging as a single executable. Cloud accounts, browser automation, automatic pull requests and automatic pushes remain outside the MVP. See [roadmap](docs/roadmap.md).
+
+## Development and contributing
+
+```bash
+npm ci
+npm run lint
+npm run typecheck
+npm test
+npm run test:coverage
+npm run build
+```
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) and [development notes](docs/development.md). Suggested GitHub topics: `ai-agents`, `claude-code`, `codex-cli`, `developer-tools`, `git-worktree`, `local-first`, `typescript`.
+
+## Disclaimer
+
+You control the provider sessions and repository. Check provider terms, usage limits, generated code, licenses and security impact before adopting a change. Loop Engineer does not bypass provider authentication or usage limits.
+
+## License
+
+[MIT](LICENSE)

SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Supported versions
+
+The project supports the latest release on the default branch during the pre-1.0 period.
+
+## Report a vulnerability
+
+Use GitHub's private vulnerability reporting feature when the repository enables it. If that option is unavailable, contact a maintainer through a private channel listed on their GitHub profile.
+
+Include the affected version, operating system, provider CLI versions, impact and a minimal reproduction. Remove credentials, private source code and raw provider transcripts.
+
+Do not open a public issue until a maintainer confirms that disclosure is safe. We will acknowledge a report, assess severity and coordinate a fix and disclosure timeline.

docs/architecture.md

@@ -0,0 +1,11 @@
+# Architecture
+
+Loop Engineer separates policy, provider adapters and workflow state.
+
+The CLI validates configuration before it resolves a repository. The orchestrator then creates a run store and detached worktree. Read-only roles use the repository root; writing roles use the worktree path. Provider adapters translate Loop Engineer permissions into provider CLI flags. The local provider accepts an argument list produced by the command policy and starts processes with `shell: false`.
+
+Zod schemas form the boundary between phases. A phase cannot consume free-form chat history. The validator accepts valid JSON or performs one mechanical repair pass for fences, trailing commas and surrounding text. It does not fill missing values.
+
+Reports derive from validated handoffs, Git numstat output and process results. The final judge cannot override failed objective gates because the orchestrator clamps its decision.
+
+The MVP keeps files on disk under `.loop-engineer/` and runs no database or daemon. The optional `loopeng gui` command starts an ephemeral loopback-only HTTP server for the lifetime of the command. Provider CLIs may use their vendor networks under their own sessions and policies.

docs/configuration.md

@@ -0,0 +1,21 @@
+# Configuration
+
+Loop Engineer reads YAML from `loop-engineer.yml` unless `--config` points elsewhere. The schema rejects unknown keys.
+
+`project.root` resolves from the directory where you start the CLI. `workflow.max_cycles` accepts 1 through 20. `workflow.max_runtime_minutes` accepts 1 through 1440.
+
+Role permissions have fixed safety constraints:
+
+| Role                                    | Required permission   |
+| --------------------------------------- | --------------------- |
+| analyst, planner, reviewer, final_judge | `read-only`           |
+| implementer, fixer                      | `workspace-write`     |
+| tester                                  | `predefined-commands` |
+
+The tester must use `local` in normal configuration. Tests may use the internal `fake` provider.
+
+Quality gates can require passing commands, reviewer approval and zero findings at configured severities. The default blocks `critical` and `high`.
+
+The `install` command records a detected install command for future use. The MVP does not run it when `allow_package_install` is false, which is the default.
+
+`security.network_access` controls network-capable agent tools, not the provider CLI's connection to its vendor service. The MVP does not grant network tools to roles.