Setup agenticloop

Setup Agentic Loop

This is an interactive setup and human-controlled profile-update skill. It is maintainer-run or human-run. Run it when:

• setting up Agentic Loop in a target project for the first time,
• source document names are non-standard or ambiguous,
• .agenticloop/project.md is setup_status: unconfirmed,
• .agenticloop/project.md needs confirmed typed document selections.
• a confirmed project needs its one-time development-stage migration or a human wants to confirm a later development-stage transition.

Do not use this skill for routine runtime document lookup. At runtime, agents read .agenticloop/project.md for overrides and fall back to conventional names. This skill performs one-time discovery so runtime agents do not need to scan the repository.

What This Skill Does

1. Scan bounded candidate paths once.
2. Propose detected documents by role, detected grouping profile, inferred task ID style, backend choice, development stage, and implementation-lane maximum.
3. Ask the human to confirm before writing.
4. Write confirmed project-map values and setup confirmation state to .agenticloop/project.md.
5. Preserve existing .agenticloop/project.md content where possible.

After this skill runs, future runtime agents use convention-first lookup plus the confirmed overrides recorded here.

Setup is complete only after the maintainer or human confirms:

• document role selections,
• task ID pattern and regex,
• grouping profile,
• backend choice.
• one development stage: greenfield, expansion, stabilization, or maintenance.

Candidate Files to Detect

Use the canonical document-role registry in agenticloop/config.json. Scan only these bounded candidates once:

rules

• AGENTS.md
• CLAUDE.md
• GEMINI.md

plan

• IMPLEMENTATION_PLAN.md
• PLAN.md
• ROADMAP.md
• docs/roadmap.md

overview

• README.md
• docs/overview.md

process

• agenticloop/AGENTIC_LOOP.md

spec

• SPEC.md
• SPECS.md
• PRD.md
• REQUIREMENTS.md
• docs/spec.md
• docs/specs/
• docs/prd/

design

• DESIGN.md
• ARCHITECTURE.md
• ARCHITECTURE_PLAN.md
• ARCHITECTURE_DESIGN.md
• docs/architecture.md
• docs/adr/

context

• CONTEXT.md
• docs/context.md

Use context for target-owned domain context, product vocabulary, or task-start context. Agentic Loop's own glossary is in agenticloop/AGENTIC_LOOP.md.

history

• CHANGELOG.md
• RELEASE-NOTES.md
• MIGRATION.md

Steps

Step 1: Scan

Look for the candidate files listed above. Identify which are present. Do not search beyond these candidates; do not scan the whole repository.

Step 2: Infer conventions

For each document role, compare the detected file against the conventional first candidate. Note non-conventional selections that would need a typed document entry in .agenticloop/project.md.

Also infer:

• the grouping profile (flat, phase, milestone, epic, or custom), defaulting to flat when no grouping is evident
• the task ID convention if it is visible in the plan
• bounded backend evidence, including only practical signals such as:
  • existing .agenticloop/project.md task_backend
  • legacy agenticloop.json taskBackend, when present
  • whether git remote origin points to GitHub
  • whether gh auth status is available, without requiring auth to finish local setup
  • existing GitHub labels such as task:*, phase:*, type:impl, blocked, approved, agent-ready
  • issue or pull-request references visible in the bounded source docs already scanned by this setup step
  • current branch names that already follow task or grouping conventions
  • presence or absence of local .agenticloop/tasks/ records
• the backend choice, defaulting to files only when no existing durable backend evidence is present
• a development-stage proposal using only bounded evidence in this order:
  1. explicit lifecycle, stability, release, compatibility, maintenance, or support statements in the selected documents;
  2. stable release tags plus documented public API, format, migration, or compatibility commitments;
  3. roadmap, release, and changelog activity; and
  4. package version, repository history, or other cheap metadata only as supporting evidence.

Never decide development stage from commit count, repository age, tests, semver, decision-record count, or plan-completion ratio alone. Present confidence, evidence, rationale, and conflicting signals to the human. The proposal is not durable policy and must not be written before explicit human confirmation. Negated or historical language such as "no compatibility policy" or an old "initial release" entry is not positive current-stage evidence. When bounded signals conflict, present no preselected stage and require the human to choose one exact allowed value.

Do not propose a document selection when the conventional default is present and no better match exists.

When inferring grouping from plan headings, use the selected plan document when one is already recorded; otherwise use the bounded plan candidates from agenticloop/config.json. Treat ##, ###, and #### headings named Phase, Milestone, or Epic as grouping evidence.

Do not use a brittle deterministic rule such as "GitHub remote means GitHub backend". Instead, present the bounded evidence you found, propose a backend with a short rationale and confidence level, and require an explicit human confirmation.

If durable GitHub workflow evidence is present, propose github or require an explicit files-backend exception from the human before writing task_backend: files.

Step 3: Propose and Confirm

Present your findings to the human in a compact list:

Detected source documents:
  rules: AGENTS.md                       (conventional - no selection needed)
  plan: ROADMAP.md                       (selection recommended)
  overview: README.md                    (conventional - no selection needed)
  design: ARCHITECTURE_PLAN.md           (selection recommended)

Detected grouping:
  grouping_profile: phase
  task_id_pattern: P<phase>-<number>

Backend evidence:
  - git remote origin: github.com/acme/widget
  - gh auth status: available
  - existing labels: agent-ready, blocked, approved, type:impl, task:P6-FU-1
  - existing issue title prefixes: P6-FU-1, P3-10-FU-1
  - local .agenticloop/tasks/: absent

Backend proposal:
  task_backend: github
  confidence: high
  rationale: existing durable GitHub issue and label workflow evidence is present

Development-stage proposal:
  development_stage: expansion
  confidence: medium
  rationale: selected roadmap and release notes describe active capability growth
  evidence: ROADMAP.md, CHANGELOG.md

Implementation-lane maximum:
  max_parallel_implementation_lanes: 5
  note: ceiling for eligible implementation lanes only, not a total-agent budget

Workflow defaults:
  default_attempt_budget: 5
  default_review_budget: 5
  default_audit_budget: 3

Proposed .agenticloop/project.md values:
  documents.plan: "ROADMAP.md"
  documents.design: "ARCHITECTURE_PLAN.md"
  task_backend: github
  grouping_profile: phase
  task_id_pattern: "P<phase>-<number>"
  task_id_regex: "^P\\d+-\\d{2,}$"
  group_closeout: true
  development_stage: expansion
  default_attempt_budget: 5
  default_review_budget: 5
  default_audit_budget: 3
  max_parallel_implementation_lanes: 5

Confirm these document selections, task naming/grouping values, backend choice,
development stage, attempt/review/audit defaults, and implementation-lane maximum? (yes / no / edit)

Ask the human to confirm before writing. Confirmation may either record typed selections or explicitly accept the defaults already shown in the project map. If they say "edit", accept their corrections, including one exact stage from the allowed set, optional development_stage_rationale, optional development_stage_revisit_when, and positive safe integer attempt, review, audit, and implementation-lane values. Reject and re-prompt invalid stage or budget input; never retain the AI proposal as a fallback for a rejected correction. If they say "no", do not write anything and leave setup_status: unconfirmed.

For task IDs, present a bounded convention selector rather than asking the human to edit task_id_pattern and task_id_regex independently. Offer the neutral T-001 convention first, a small set of Agentic Loop-compatible examples such as TASK-001, and a grouping-specific example such as P1-01 only when that grouping applies. Treat each preset as one atomic pattern/regex pair. A custom choice is advanced: require an anchored, compilable, bounded regex plus one filename-safe example that matches it before confirmation. Reject path separators, whitespace, unsafe filename characters, substring-only regexes, backreferences, nested quantifiers, and overlong expressions. State that automatic allocation supports T-### only; other conventions require an explicit task ID until a compatible allocator exists.

For an existing confirmed project missing stage, present this as a one-time stage migration; do not silently assign a default or bundle document-selection, backend, naming, or grouping changes into that confirmation. For an existing valid stage, offer a profile update only when a human explicitly chooses it. Show the current stage, require the human to enter or retain the exact value, then require another explicit confirmation before writing. Declining that optional profile update retains the existing values and continues routine setup or adapter refresh. Agents may propose a later transition but must never apply it themselves. Non-interactive setup fails closed unless a valid stage was previously human-confirmed and persisted.

If the human keeps task_backend: files despite durable GitHub workflow evidence, ask them to state the explicit exception in one short sentence and record that sentence in backend_evidence_summary when writing the file.

Step 4: Write Overrides

Write only the confirmed non-conventional selections and confirmed grouping/task convention values to .agenticloop/project.md frontmatter. Do not write a document selection for a role whose conventional path was detected.

After confirmation, always write:

• setup_status: confirmed
• setup_confirmed_at: <YYYY-MM-DD>
• setup_confirmed_by: <human or maintainer>
• task_backend: <confirmed backend choice>
• development_stage: <human-confirmed greenfield|expansion|stabilization|maintenance>
• default_attempt_budget: <positive safe integer; default 5>
• default_review_budget: <positive safe integer; default 5>
• default_audit_budget: <positive safe integer; default 3>
• max_parallel_implementation_lanes: <positive safe integer; default 5>

Do this even when no non-conventional document selections are needed and the human only confirms the default conventions.

When helpful, also write these optional backend-confirmation notes:

• backend_confirmed_at: <YYYY-MM-DD>
• backend_confirmed_by: <human or maintainer>
• backend_evidence_summary: <one-line backend evidence summary or explicit files exception>

When the human or target setup already knows the engineer model's active context window, the maintainer may also record:

• engineer_context_window_tokens: <positive integer>

When .agenticloop/project.md already exists:

• Parse the existing frontmatter.
• Merge in the new override keys.
• Preserve existing frontmatter values that are not being overridden.
• Preserve the body of the file, including the exact ## Verification Operating Facts body, byte-for-byte.
• Do not add, remove, normalize, infer, or update VF-... facts during setup. Setup has no evidence or strategy-approval authority; the maintainer updates the current profile only through [[verification-evidence]].
• If the human declines confirmation, leave setup_status: unconfirmed.

When .agenticloop/project.md does not exist, write a fresh file using the project-map shape: YAML frontmatter with setup_status, setup_confirmed_at, setup_confirmed_by, development_stage, default_attempt_budget, default_review_budget, default_audit_budget, max_parallel_implementation_lanes, task_backend, task_id_pattern, task_id_regex, task_file_template, optional engineer_context_window_tokens, and optional typed documents keys, followed by a # Agentic Loop Project Map heading and the canonical empty ## Verification Operating Facts section. Do not invent an initial fact. Alternatively, tell the human to run npx agenticloop setup, which scaffolds the overlay and confirms the project profile in one guided pass, or npx agenticloop init, which creates the file automatically without guidance.

Do not write model IDs, provider names, or reasoning effort settings to .agenticloop/project.md. Those belong in agenticloop.json under adapters.<host>.roleSettings.

Step 5: Explain Next Steps

After writing, tell the human:

• which selections were written,
• which grouping or task-ID conventions were recorded,
• which backend choice was confirmed and why,
• which development stage the human confirmed, the bounded rationale, and any revisit trigger,
• that the implementation-lane maximum is a ceiling only for eligible implementation lanes,
• who confirmed the setup and on what date,
• that future runtime agents will use the typed selections plus bounded candidate defaults,
• that agenticloop validate can verify the project map.

What This Skill Must Not Do

• Perform broad runtime document discovery on every agent turn.
• Write model IDs, provider names, or reasoning effort values.
• Overwrite the body of .agenticloop/project.md beyond frontmatter overrides.
• Guess at document paths without candidate detection.
• Run agenticloop init automatically; only write confirmed overrides.
• Persist or transition development_stage without explicit human confirmation.