Skip to content

docs: add Intelligence Over Scripts to system prompt and PR issue-linkage guidance #2446

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alex-solovyev merged 1 commit into from
Feb 27, 2026
Merged

docs: add Intelligence Over Scripts to system prompt and PR issue-linkage guidance #2446

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .agents/prompts/build.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,13 @@ Before ANY file modification: run `~/.aidevops/agents/scripts/pre-edit-check.sh`
- Progressive disclosure: pointers to subagents, not inline content
- MCP tools loaded on-demand per subagent (reduces context overhead)

# Intelligence Over Scripts (CORE PRINCIPLE)
When fixing orchestration, supervisor, or workflow bugs: improve agent guidance docs — do NOT add bash scripts, helper utilities, or deterministic state-tracking layers. You are an LLM. You can reason about whether two issues are duplicates, whether a task is stuck, or how to prioritize work. A regex or title-prefix match cannot. The framework previously had 37,000 lines of fragile bash orchestration that was never reliable. It was replaced with intelligence-guided agents for good reason.
- If your proposed fix adds a `.sh` file or state mechanism: STOP. You are going in the wrong direction.
- If your proposed fix adds a paragraph of clear guidance to an agent doc: you are on the right track.
- Helper scripts are appropriate ONLY for deterministic utilities (version bumping, file discovery, credential lookup) — never for decisions requiring judgment.
- When you encounter a problem that "could be solved with a script", ask: could this be solved by telling the agent what to look for and how to decide? If yes, update the guidance doc instead.

# Working Directories
~/.aidevops/.agent-workspace/
├── work/[project]/ # Persistent project files
Expand Down
1 change: 1 addition & 0 deletions .agents/scripts/commands/full-loop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -416,6 +416,7 @@ After task completion, the loop automatically:

1. **Preflight**: Runs quality checks, auto-fixes issues
2. **PR Create**: Verifies `gh auth`, rebases onto `origin/main`, pushes branch, creates PR with proper title/body
**Issue linkage in PR body (MANDATORY):** The PR body MUST include `Closes #NNN` (or `Fixes`/`Resolves`) for every related issue — this is the ONLY mechanism that creates a GitHub PR-issue link. Before writing the PR body, search for ALL open issues related to your task: `gh issue list --state open --search "<task description keywords>"`. Issues may exist under different title formats (e.g., `coderabbit: Fix X` and `t1234: Fix X` for the same task). Include closing keywords for every match. A comment like "Resolved by PR #NNN" does NOT create a link — only closing keywords in the PR body do.
3. **Label Update**: Update linked issue to `status:in-review` (see below)
4. **PR Review**: Monitors CI checks and review status
5. **Merge**: Squash merge (without `--delete-branch` when in worktree)
Expand Down