@tea-agent/loop-agent 0.1.0

package/docs/agent-dag-runner.md

@@ -0,0 +1,40 @@
+# Agent DAG Runner
+
+Agent DAG is loop-agent's declarative orchestration runtime. A DAG decomposes work into nodes, runs eligible ranks in order, records artifacts, and uses gates for review and verification.
+
+## Basic Use
+
+```bash
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
+```
+
+`<temp-dir>` is the platform-native temp directory. On Windows, pass native paths for actual `--output`, `--dag`, and `--cwd` values.
+
+## Executors
+
+- `static`: deterministic generated artifacts or notes
+- `shell`: verification and file-system checks
+- `pi`: planning, review, diagnosis, and bounded writing when a node sets `toolProfile: "write"`
+- `cursor`: optional bounded write backend when explicitly enabled
+
+## Skills
+
+DAG specs may declare `defaults.skills`, `skillsByRole`, and node-level `skills`. The runner resolves local instructions from `skills/<skill-name>/SKILL.md` and records resolution metadata in each node's `skills.json` artifact.
+
+The `loop-agent` skill lives at `skills/loop-agent/SKILL.md`. The legacy root `skill/SKILL.md` path is retained only as a compatibility fallback for older worktrees.
+
+## Artifacts
+
+DAG artifacts belong under:
+
+```text
+.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/
+```
+
+Root `artifacts/` is not a valid default DAG artifact location.
+
+## Shell Gates
+
+- `shell.verdictGate` reads `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json` from the injected current run directory; 不应自行发现 active run paths.

package/docs/cursor-executor-usage.md

@@ -0,0 +1,25 @@
+# Cursor Executor Usage
+
+Cursor is used for bounded write implementation. Every Cursor write task must define scope explicitly.
+
+## Required Prompt Fields
+
+- task id
+- objective
+- allowed paths
+- forbidden paths
+- constraints
+- expected verification
+- instruction to preserve unrelated changes
+
+## One-Shot Helper
+
+```bash
+loop-agent cursor-prompt \
+  --cwd . \
+  --timeout 1800000 \
+  --model composer-2.5 \
+  "<bounded task prompt>"
+```
+
+After Cursor returns, the main session must inspect the diff and run the relevant verification commands.

package/docs/decisions/README.md

@@ -0,0 +1,3 @@
+# Decisions
+
+Use this directory for architecture decision records.

package/docs/design/README.md

@@ -0,0 +1,36 @@
+# Design Notes
+
+`docs/design/` contains planning notes for using `loop-agent` as the repo-local runtime inside a larger product-line agent platform. These documents are design inputs, not proof that the capability already exists in `src/`.
+
+## Documents
+
+| Document | Purpose |
+|---|---|
+| `产品线共享知识库.md` | Product-line docs repository as the upstream source of truth |
+| `研发模式.md` | 10-working-day Feature team workflow |
+| `1个月规划.md` | First-month landing plan |
+| `1月wbs.md` | First-month WBS and ownership |
+| `六个月规划.md` | Six-month roadmap and target architecture |
+| `taskspec-to-loop-agent-mapping.md` | Contract for adapting product-line TaskSpec into `loop-agent` tasks |
+| `state-and-failure-taxonomy.md` | Canonical status and failure taxonomy across docs, Task Pool, DAG, and Loop |
+
+## Current Implementation Boundary
+
+`loop-agent` currently owns a repo-local harness, Agent DAG generation/validation/execution, shell verification, artifacts, reports, and Loop state. It is not the product-line Task Pool, Orchestrator, docs-sync service, Git/CI platform, or artifact store.
+
+The design documents use two kinds of profile names:
+
+- Business task profiles: `backend-feature`, `frontend-feature`, `qa-casegen`, `qa-testcode`, `reviewer-gate`.
+- `loop-agent dag run-task --profile` governance profiles: `auto`, `minimal`, `standard`, `reviewed`, `supervised`.
+
+Do not pass business task profiles directly to `loop-agent dag run-task --profile` unless the CLI is explicitly extended to support them. Use `taskspec-to-loop-agent-mapping.md` to route business profiles to current governance profiles.
+
+## Maintenance Rules
+
+When these design notes change:
+
+1. Keep TaskSpec fields, status names, failure categories, and command examples consistent with the contract docs.
+2. Mark future platform components as target architecture unless they exist in `src/` or `scripts/`.
+3. Update `taskspec-to-loop-agent-mapping.md` whenever `src/task/config-types.ts` or DAG profile routing changes.
+4. Update `state-and-failure-taxonomy.md` whenever DAG report categories, Loop failure classes, or Task Pool states change.
+5. Run `bash scripts/check-repo.sh`.

package/docs/development-principles.md

@@ -0,0 +1,71 @@
+# Development Principles
+
+loop-agent is a workflow runtime for agentic coding work. The repository should stay small, explicit, and verifiable.
+
+## Operating Stance
+
+The project uses a human-led, agent-executed engineering model. Agents may implement, verify, and summarize, but durable intent and completion evidence must live in the repository.
+
+- The repository is the record system. Decisions, contracts, plans, tests, reports, and handoffs belong in tracked files.
+- `AGENTS.md` is an operating map, not a knowledge dump. Long-lived methodology and decisions belong under `docs/`.
+- Work advances in small, reversible, verifiable increments.
+- Baseline verification comes before new work when the current state is uncertain.
+- Completion is defined by fresh evidence, not by intent or confidence.
+
+## Principles
+
+1. One task advances one bounded work block.
+2. Search existing code, docs, scripts, and tests before designing new behavior.
+3. Shell verification is the completion authority.
+4. Runtime state belongs in `.harness/`; durable decisions belong in `docs/`.
+5. Pi writer nodes and optional Cursor write execution must be bounded by explicit allowed and forbidden paths.
+6. Pi review/planning paths are advisory unless followed by deterministic verification.
+7. Repeated constraints should become docs, tests, scripts, checks, or templates.
+8. Do not keep hidden process state only in chat.
+9. Do not add placeholders as completed implementation.
+10. Prefer existing local patterns before adding new abstractions.
+
+## Repository Shape
+
+- Source lives in `src/`.
+- Tests live in `test/`.
+- Skill instructions live in `skills/`.
+- Verification and maintenance scripts live in `scripts/`.
+- Governance and handoff artifacts live in `docs/`.
+
+## Change Discipline
+
+For behavior changes, update tests. For workflow or command changes, update docs and examples. For governance changes, update `harness.json` and the relevant check scripts.
+
+When work affects requirements, behavior, cross-command contracts, or harness rules, update the corresponding durable artifact:
+
+- design or contract docs for changed expectations
+- tests or verification scripts for changed behavior
+- progress logs or reports for non-trivial handoff evidence
+- ADRs for architecture or public contract decisions
+- templates when a repeated process becomes reusable
+
+Do not mix unrelated refactors, new features, and broad documentation migration in one work block unless the contract explicitly says why they must move together.
+
+## Search And Reuse
+
+Before implementing, inspect the existing system:
+
+- Use CodeGraph first when the repository is indexed and the task needs code understanding.
+- Use `rg` for text search and `fd` for file discovery when available.
+- Read nearby tests and helpers before introducing new helpers.
+- Prefer structured parsers and existing local APIs over ad hoc string manipulation.
+
+Assume the system may already contain a partial solution until search proves otherwise.
+
+## Completion Discipline
+
+A completion claim must answer:
+
+- what changed
+- why this approach was chosen
+- which command verified it and what the result was
+- whether contracts, docs, tests, or scripts were affected
+- what risk or follow-up remains
+
+If verification fails, report the failing command and observed state instead of softening the completion definition.