Restructure into publish-ready codex-self-iter plugin repository

Dremig · Dremig · commit 04bc6a159261 · 2026-04-21T12:24:32.000+08:00
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
@@ -0,0 +1,18 @@
+{
+  "name": "codex-self-iter",
+  "version": "0.1.0",
+  "description": "Autonomous small-step self-iteration loop for Codex-driven task execution.",
+  "author": {
+    "name": "Dremig"
+  },
+  "license": "WTFPL",
+  "interface": {
+    "displayName": "Codex Self Iter",
+    "summary": "Read a plan file, auto-generate next steps, execute, review, and iterate until stop.",
+    "tags": [
+      "automation",
+      "agent",
+      "iteration"
+    ]
+  }
+}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,21 @@
+name: ci
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install package and test deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+      - name: Run tests
+        run: pytest -q
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+
+.codex-self-iter/
+.codex-stop
+
+.DS_Store
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 - 2026-04-21
+
+- Initial public repository structure for `codex-self-iter`.
+- Added Python package layout (`src/`), CLI entrypoint, and tests.
+- Added plugin manifest at `.codex-plugin/plugin.json`.
+- Added GitHub Actions CI for lint-free test run.
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,13 @@
+DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+Version 2, December 2004
+
+Copyright (C) 2026 Dremig
+
+Everyone is permitted to copy and distribute verbatim or modified
+copies of this license document, and changing it is allowed as long
+as the name is changed.
+
+DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+0. You just DO WHAT THE FUCK YOU WANT TO.
diff --git a/README.md b/README.md
@@ -1 +1,86 @@
-# iter-codex
+# codex-self-iter
+
+`codex-self-iter` is a plugin-style repository that runs a continuous autonomous loop for coding tasks:
+
+1. Read `TASK.md` + `plan.md`
+2. Generate one small next step
+3. Execute the step via agent command
+4. Review result and decide whether to continue
+5. Repeat until no meaningful next action exists or user stops it
+
+## Repository Layout
+
+```text
+.
+├── .codex-plugin/plugin.json
+├── src/codex_self_iter/
+├── tests/
+├── examples/
+├── scripts/
+├── pyproject.toml
+└── .github/workflows/ci.yml
+```
+
+## Quick Start
+
+1. Install locally:
+
+```bash
+pip install -e .[dev]
+```
+
+2. Prepare task files in your workspace:
+
+- `TASK.md` (optional)
+- `plan.md` (required)
+
+3. Run:
+
+```bash
+python3 -m codex_self_iter \
+  --workspace . \
+  --task-file TASK.md \
+  --plan-file plan.md \
+  --state-dir .codex-self-iter \
+  --agent-command-template "codex exec --auto --prompt-file {prompt_file}"
+```
+
+Or use:
+
+```bash
+./scripts/run-local.sh .
+```
+
+## Stop Conditions
+
+- Create `.codex-self-iter/STOP`
+- Or create workspace-level `.codex-stop`
+- Or interrupt process manually
+
+## Output Artifacts
+
+- `.codex-self-iter/prompts/`: planner/executor/reviewer prompts
+- `.codex-self-iter/logs/iterations.jsonl`: loop records
+- `.codex-self-iter/status.json`: last iteration state
+
+## Configuration
+
+See `config.example.toml`.
+
+Important fields:
+
+- `agent_command_template` must include `{prompt_file}`
+- `max_iterations = 0` means unbounded loop
+- `max_stagnation` prevents infinite cycling on identical `next_focus`
+
+## Development
+
+Run tests:
+
+```bash
+pytest -q
+```
+
+## Security and Automation Boundary
+
+The loop is autonomous at application logic level but still bounded by host permissions, sandbox policy, and tool confirmations.
diff --git a/config.example.toml b/config.example.toml
@@ -0,0 +1,25 @@
+# Required:
+# Must include {prompt_file}; may include {workspace}.
+agent_command_template = "codex exec --auto --prompt-file {prompt_file}"
+
+# 0 means unbounded loop until stop condition.
+max_iterations = 0
+
+# Stop when reviewer keeps giving same next_focus for this many rounds.
+max_stagnation = 4
+
+# Per command timeout.
+command_timeout_sec = 1200
+
+# Create this file under state-dir to stop loop.
+stop_file_name = "STOP"
+
+# Create this file under workspace to stop loop.
+global_stop_file_name = ".codex-stop"
+
+# Prompt hint only.
+planner_model_hint = "balanced"
+reviewer_model_hint = "strict"
+
+# Number of history rows fed back to planner each round.
+history_tail = 8
diff --git a/examples/TASK.md b/examples/TASK.md
@@ -0,0 +1,3 @@
+# Task
+
+Implement and continuously optimize feature X until acceptance criteria are met.
diff --git a/examples/plan.md b/examples/plan.md
@@ -0,0 +1,27 @@
+# Project Plan
+
+## Goal
+
+Build and refine feature X until acceptance criteria are satisfied.
+
+## Acceptance Criteria
+
+1. Core workflow passes integration tests.
+2. Error handling covers key edge cases.
+3. Performance meets target baseline.
+
+## Constraints
+
+1. Keep API backward compatible.
+2. Do not modify files outside `src/` and `tests/`.
+3. Add or update tests for every behavior change.
+
+## Priorities
+
+1. Correctness
+2. Test coverage
+3. Performance optimization
+
+## Iteration Strategy
+
+Use small, atomic steps and verify each step with focused checks.
diff --git a/pyproject.toml b/pyproject.toml
@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codex-self-iter"
+version = "0.1.0"
+description = "Self-iterating autonomous coding loop for Codex-style agents."
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "WTFPL"}
+authors = [
+  {name = "Dremig"}
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.2"]
+
+[project.scripts]
+codex-self-iter = "codex_self_iter.__main__:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
diff --git a/scripts/run-local.sh b/scripts/run-local.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+python3 -m codex_self_iter \
+  --workspace "${1:-.}" \
+  --task-file "${2:-TASK.md}" \
+  --plan-file "${3:-plan.md}" \
+  --state-dir "${4:-.codex-self-iter}" \
+  --config "${5:-config.example.toml}"
diff --git a/src/codex_self_iter/__init__.py b/src/codex_self_iter/__init__.py
@@ -0,0 +1,5 @@
+"""codex-self-iter package."""
+
+from .runner import run
+
+__all__ = ["run"]
diff --git a/src/codex_self_iter/__main__.py b/src/codex_self_iter/__main__.py
@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .runner import run
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run Codex-style self-iteration loop.")
+    parser.add_argument("--workspace", default=".", help="Repository root")
+    parser.add_argument("--task-file", default="TASK.md", help="Task brief file")
+    parser.add_argument("--plan-file", default="plan.md", help="Plan file")
+    parser.add_argument("--state-dir", default=".codex-self-iter", help="State/log directory")
+    parser.add_argument(
+        "--agent-command-template",
+        default="codex exec --auto --prompt-file {prompt_file}",
+        help="Command template; supports {prompt_file} and {workspace}",
+    )
+    parser.add_argument("--config", default="", help="TOML config path (optional)")
+    args = parser.parse_args()
+
+    return run(
+        workspace=Path(args.workspace).resolve(),
+        task_file_name=args.task_file,
+        plan_file_name=args.plan_file,
+        state_dir_name=args.state_dir,
+        agent_command_template=args.agent_command_template,
+        config_path=Path(args.config).resolve() if args.config else None,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/src/codex_self_iter/config.py b/src/codex_self_iter/config.py
@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover
+    tomllib = None  # type: ignore
+
+
+@dataclass
+class LoopConfig:
+    agent_command_template: str
+    max_iterations: int = 0
+    max_stagnation: int = 4
+    command_timeout_sec: int = 1200
+    stop_file_name: str = "STOP"
+    global_stop_file_name: str = ".codex-stop"
+    planner_model_hint: str = "balanced"
+    reviewer_model_hint: str = "strict"
+    history_tail: int = 8
+
+
+def read_text(path: Path, default: str = "") -> str:
+    if not path.exists():
+        return default
+    return path.read_text(encoding="utf-8")
+
+
+def load_config(config_path: Path | None, default_agent_cmd: str) -> LoopConfig:
+    if config_path is None:
+        return LoopConfig(agent_command_template=default_agent_cmd)
+    if tomllib is None:
+        raise RuntimeError("tomllib not available, cannot read TOML config.")
+    raw = tomllib.loads(read_text(config_path))
+    return LoopConfig(
+        agent_command_template=raw.get("agent_command_template", default_agent_cmd),
+        max_iterations=int(raw.get("max_iterations", 0)),
+        max_stagnation=int(raw.get("max_stagnation", 4)),
+        command_timeout_sec=int(raw.get("command_timeout_sec", 1200)),
+        stop_file_name=str(raw.get("stop_file_name", "STOP")),
+        global_stop_file_name=str(raw.get("global_stop_file_name", ".codex-stop")),
+        planner_model_hint=str(raw.get("planner_model_hint", "balanced")),
+        reviewer_model_hint=str(raw.get("reviewer_model_hint", "strict")),
+        history_tail=int(raw.get("history_tail", 8)),
+    )
diff --git a/src/codex_self_iter/prompts.py b/src/codex_self_iter/prompts.py
diff --git a/src/codex_self_iter/runner.py b/src/codex_self_iter/runner.py
diff --git a/tests/test_runner.py b/tests/test_runner.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Task`
	`2`	`+`
	`3`	`+Implement and continuously optimize feature X until acceptance criteria are met.`