diff --git a/.claude/agents/codex.md b/.claude/agents/codex.md new file mode 100644 index 0000000..4191438 --- /dev/null +++ b/.claude/agents/codex.md @@ -0,0 +1,13 @@ +# Project Agent Handoff + +Use AGENTS.md at repo root as the source of truth for coding rules and guardrails. + +Key Rules +- Code first, concise rationale after. If uncertain, say "Uncertain:". +- Keep diffs minimal; follow existing patterns and `analysis_options.yaml`. +- Validate with `scripts/check.sh` (format/analyze/test) before completion. +- Ask for approval before dependency changes, build config edits, or network access. + +Templates +- Task and PR templates are in `AGENTS.md` and `doc/agents/codex_prompt_templates.md`. + diff --git a/.github/workflows/flutter_ci.yml b/.github/workflows/flutter_ci.yml new file mode 100644 index 0000000..06e55df --- /dev/null +++ b/.github/workflows/flutter_ci.yml @@ -0,0 +1,31 @@ +name: Flutter CI + +on: + pull_request: + push: + branches: [ main, master ] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Flutter + uses: subosito/flutter-action@v2 + with: + channel: stable + + - name: Flutter Pub Get + run: flutter pub get + + - name: Format check + run: dart format --output=none --set-exit-if-changed . + + - name: Analyze + run: flutter analyze + + - name: Test + run: flutter test + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..56ba8ea --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,69 @@ +Codex Agent Guide for SubManager + +Scope +- Applies to the entire repository unless a more specific rule exists deeper in the tree. +- Precedence: project AGENTS.md > project .claude/agents > user ~/.claude > default Codex CLI rules. Direct system/developer instructions always win. + +Goals +- Accelerate small, safe changes with consistent quality. +- Keep diffs minimal, focused, and aligned with Flutter best practices. + +Guardrails +- Workspace only: modify files within this repo. Ask before adding dependencies or using network. +- Safety: avoid destructive actions (file deletions, rewrites, config changes) unless explicitly requested. +- Responses: be concise; code first, short rationale after. If uncertain, prefix with "Uncertain:". If multiple viable solutions, show the top 2 briefly. +- Planning: for multi‑step tasks, maintain an update_plan with exactly one in_progress step. + +Coding Standards +- Language: Dart/Flutter (SDK >= 3.0). Respect `analysis_options.yaml` (flutter_lints baseline). +- Style/format: use `dart format .` and keep changes minimal. Avoid one‑letter variable names; avoid inline comments unless requested. +- Structure: follow existing file/module patterns and naming. Do not introduce new frameworks or architectural shifts without approval. +- Tests: add or update tests when behavior changes or bugs are fixed (if feasible). Keep tests scoped to the change. + +Validation +- Always run local checks via `scripts/check.sh` before proposing completion: + - formatting check: `dart format --set-exit-if-changed .` + - static analysis: `flutter analyze` + - unit/widget tests: `flutter test` (ok if none exist) +- UI changes: include brief description of visual impact; screenshots if readily available by the user. + +Sensitive Areas (require explicit approval) +- Android/iOS/macOS build configs, signing, bundle identifiers, Gradle/Kotlin/Swift project settings. +- Dependency graph changes (pubspec.yaml add/remove/upgrade). +- Network access, calling external APIs, or adding secrets. + +Operational Conventions +- Branch naming: `codex/-` (e.g., `codex/fix-url-matcher`). +- Commits: Conventional Commits preferred (e.g., `fix: correct url matching for X`). +- PR description template: + - Summary: what/why + - Changes: key files and decisions + - Validation: how verified (analyze/tests/manual) + - Risk & Rollback: potential impact and quick rollback steps + +Task Template (author-provided) +--- +Next: +Complexity: simple | medium | complex + +Context +- Problem / goal: +- Constraints / non‑goals: +- Repro or commands: + +Done When +- [ ] Behavior verified (`scripts/check.sh` passes) +- [ ] Tests/docs updated if applicable +--- + +Commands +- Lint/analyze/tests: `scripts/check.sh` +- Auto‑format: `scripts/fix.sh` + +References & External Facts +- Prefer official docs and code‑local references. If citing sources, include plain URLs or file paths in PR descriptions (avoid footnote citation syntaxes). + +Notes from ~/.claude (adapted) +- Few‑shot examples improve accuracy; include small before/after or sample input→output when helpful. +- Use structured thinking internally; present only concise, actionable outputs here. + diff --git a/doc/agents/codex_prompt_templates.md b/doc/agents/codex_prompt_templates.md new file mode 100644 index 0000000..eeeaee8 --- /dev/null +++ b/doc/agents/codex_prompt_templates.md @@ -0,0 +1,70 @@ +Codex Prompt Templates + +Note +- Keep prompts concise and specific. Include before/after or small input→output examples when helpful. +- Use the Task Template in AGENTS.md for clarity and a crisp definition of Done. + +Next Task Format (from ~/.claude) +--- +Next: +Complexity: simple | medium | complex +--- + +Bugfix Prompt +--- +Context +- Problem: +- Repro: +- Observed: +- Expected: +- Constraints / Non‑goals: + +Done When +- scripts/check.sh passes; behavior verified via repro +- Tests/docs updated if applicable +--- + +Small Feature Prompt +--- +Context +- Goal: +- Entry points: +- Data/State impact: +- Constraints / Non‑goals: + +Done When +- Feature is reachable and works +- scripts/check.sh passes; minimal tests if feasible +--- + +Refactor Prompt (No Behavior Change) +--- +Context +- Target: +- Motivation: +- Safety: + +Done When +- Same behavior; cleaner structure +- scripts/check.sh passes +--- + +UI Change Prompt +--- +Context +- Screen/Widget: +- Visual Goal: +- Theming/Adaptivity: + +Done When +- Visual change implemented; screenshots added in PR by human +- scripts/check.sh passes +--- + +Code Review Aid +--- +- Summarize intent and key diffs +- Verify formatting, analysis, and tests pass +- Flag risks; suggest targeted follow‑ups +--- + diff --git a/scripts/check.sh b/scripts/check.sh new file mode 100755 index 0000000..b7d812e --- /dev/null +++ b/scripts/check.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +set -euo pipefail + +echo "==> Formatting check" +if command -v dart >/dev/null 2>&1; then + dart format --output=none --set-exit-if-changed . +else + echo "dart not found in PATH" >&2 + exit 1 +fi + +echo "==> Static analysis" +flutter analyze + +echo "==> Tests" +flutter test + +echo "\nAll checks passed." + diff --git a/scripts/fix.sh b/scripts/fix.sh new file mode 100755 index 0000000..718afdc --- /dev/null +++ b/scripts/fix.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -euo pipefail + +echo "==> Formatting code" +dart format . + +echo "Formatting complete." +