Skip to content

Commit de261ac

Browse files
jaruesinkjaruesink
committed
Refactor TaskPromptBuilder documentation to improve alignment with updated directory structure. Key changes include:
- Adjusted resource strategy to utilize `workspace/` for project-specific artifacts. - Updated output packaging instructions for task prompt files to fit the new structure. - Enhanced clarity on validation and communication expectations for task outputs. These updates aim to streamline the task prompt creation process and enhance usability for developers within the DevAgent framework.
1 parent 5f08de5 commit de261ac

2 files changed

Lines changed: 229 additions & 0 deletions

File tree

‎.devagent/features/2025-10-01_agent-execution-directive/README.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Agent Execution Directive
2+
3+
- **Status:** planning
4+
- **Owners:** @jaruesink
5+
- **Summary:** Add explicit execution directives to all agent instruction sheets so agents execute immediately when invoked instead of describing what they would do. Fixes the "describe vs. do" behavior issue.
6+
- **Related missions:** Enables agents to work autonomously without requiring approval for every action, accelerating DevAgent workflow velocity
7+
- **Latest spec:** TBD - creating task plan first
8+
- **Latest research:** N/A - internal tooling improvement based on observed behavior
9+
10+
## Changelog
11+
12+
| Date | Update | Agent/Owner |
13+
|------|--------|-------------|
14+
| 2025-10-01 | Created feature hub | @jaruesink |
15+
| 2025-10-01 | Task planning complete (3 tasks, 17 subtasks) | #TaskPlanner / @jaruesink |
16+
17+
## Open Decisions
18+
19+
- Should execution directive be in Mission section or separate section?
20+
- Do we need different directives for different agent types (creator vs. executor)?
21+
- Should we add safeguards for destructive operations?
22+
23+
## Problem Statement
24+
25+
Current agent behavior: When invoked with `#AgentName`, agents default to **describing** what they would do rather than **executing** the workflow immediately. This causes friction and requires manual intervention to actually get work done.
26+
27+
**Root causes:**
28+
1. Default AI assistant behavior (trained to be cautious and explain)
29+
2. Missing explicit execution directive in agent instruction sheets
30+
3. Ambiguous language ("Request missing info" sounds procedural, not imperative)
31+
4. No clear "you are now executing" trigger
32+
33+
**Impact:** Every agent invocation requires follow-up to actually execute, slowing workflow velocity and reducing agent autonomy.
34+
35+
## Solution
36+
37+
Add explicit execution directive to all agent instruction sheets that tells the AI:
38+
- Execute immediately when invoked with required inputs
39+
- Do not summarize, describe, or request approval
40+
- Only pause for missing REQUIRED inputs or blocking errors
41+
42+
## Task Artifacts
43+
44+
- `tasks/2025-10-01_execution-directive-task-plan.md` — Implementation task plan (3 tasks, 17 subtasks)
45+
46+
## Implementation Summary
47+
48+
**Task 1: Define Execution Directive Standard** (3 subtasks)
49+
- Draft standard execution directive text
50+
- Decide placement in agent files (recommendation: dedicated section after Mission)
51+
- Update agent template
52+
53+
**Task 2: Update All Agent Instruction Sheets** (12 subtasks)
54+
- Add execution directive to all 12 agent files
55+
- Target: `.devagent/core/agents/*.md` (after restructure completes)
56+
57+
**Task 3: Test Execution Behavior** (3 subtasks)
58+
- Test agents execute immediately
59+
- Test agents pause for missing required inputs
60+
- Document behavior change
61+
62+
**Blocked By:** Core-workspace-split restructure must complete first
63+
64+
**Success Signal:** Agents execute workflows immediately using tools instead of describing what they would do
65+

‎.devagent/features/2025-10-01_agent-execution-directive/tasks/2025-10-01_execution-directive-task-plan.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Agent Execution Directive Implementation Plan
2+
3+
- Owner: #TaskPlanner / @jaruesink
4+
- Last Updated: 2025-10-01
5+
- Status: Draft
6+
- Related Feature: `.devagent/features/2025-10-01_agent-execution-directive/`
7+
- Notes: Execute this AFTER core-workspace-split completes to avoid merge conflicts
8+
- File Location: `.devagent/features/2025-10-01_agent-execution-directive/tasks/2025-10-01_execution-directive-task-plan.md`
9+
10+
## Summary
11+
12+
Add explicit execution directives to all 12 agent instruction sheets to fix "describe vs. do" behavior. When agents are invoked with `#AgentName` and required inputs, they should execute workflows immediately using available tools instead of describing what they would do. This single change dramatically improves agent autonomy and workflow velocity.
13+
14+
## Scope & Assumptions
15+
16+
- **Scope focus:** Update all agent instruction sheets with execution directive
17+
- **Key assumptions:**
18+
- Agents are currently in `.devagent/agents/` but will move to `.devagent/core/agents/` (wait for restructure completion)
19+
- Execution directive should be prominent (Mission section or dedicated section)
20+
- Same directive pattern works for all agent types
21+
- **Out of scope:**
22+
- Changing agent workflow logic
23+
- Adding new safeguards for destructive operations (handle per-agent if needed)
24+
- External documentation updates
25+
26+
## Tasks
27+
28+
### Task 1: Define Execution Directive Standard
29+
30+
- **Objective:** Create standard execution directive text and decide placement in agent files
31+
- **Dependencies:** None
32+
- **Subtasks:**
33+
1. `Draft execution directive text` — Create clear, imperative directive that tells AI to execute immediately
34+
- Template: "When invoked with `#AgentName` and required inputs, **EXECUTE IMMEDIATELY**. Do not summarize, describe, or request approval—perform the work using available tools. Only pause for missing REQUIRED inputs or blocking errors."
35+
- Acceptance: Directive is clear, concise, and uses imperative language
36+
2. `Decide placement in agent files` — Determine where directive appears (Mission section, separate Execution Directive section, or Expected Output)
37+
- Options: (a) Add to Mission section, (b) New section after Mission, (c) Add to Expected Output
38+
- Recommendation: New dedicated section "## Execution Directive" immediately after Mission for visibility
39+
- Acceptance: Placement decision documented with rationale
40+
3. `Create agent template update` — Update `.devagent/templates/agent-brief-template.md` to include execution directive section
41+
- Entry point: `.devagent/templates/agent-brief-template.md` (will be `.devagent/core/templates/agent-brief-template.md` after restructure)
42+
- Acceptance: Template includes execution directive section with standard text
43+
- **Validation plan:** Review directive text with @jaruesink, confirm it addresses "describe vs. do" issue
44+
45+
### Task 2: Update All Agent Instruction Sheets
46+
47+
- **Objective:** Add execution directive to all 12 agent files
48+
- **Dependencies:** Task 1 complete, core-workspace-split restructure complete (agents in `.devagent/core/agents/`)
49+
- **Subtasks:**
50+
1. `Update AgentBuilder.md` — Add execution directive section
51+
- Entry point: `.devagent/core/agents/AgentBuilder.md`
52+
- Placement: After Mission section (line 6)
53+
- Acceptance: Execution directive added, no other content changed
54+
2. `Update FeatureBrainstormAgent.md` — Add execution directive section
55+
- Entry point: `.devagent/core/agents/FeatureBrainstormAgent.md`
56+
- Acceptance: Execution directive added
57+
3. `Update FeatureClarifyAgent.md` — Add execution directive section
58+
- Entry point: `.devagent/core/agents/FeatureClarifyAgent.md`
59+
- Acceptance: Execution directive added
60+
4. `Update ProductMissionPartner.md` — Add execution directive section
61+
- Entry point: `.devagent/core/agents/ProductMissionPartner.md`
62+
- Acceptance: Execution directive added
63+
5. `Update ResearchAgent.md` — Add execution directive section
64+
- Entry point: `.devagent/core/agents/ResearchAgent.md`
65+
- Note: Already has "Invocation assumption" line 7, integrate with execution directive
66+
- Acceptance: Execution directive added, invocation assumption preserved or merged
67+
6. `Update SpecArchitect.md` — Add execution directive section
68+
- Entry point: `.devagent/core/agents/SpecArchitect.md`
69+
- Acceptance: Execution directive added
70+
7. `Update TaskPlanner.md` — Add execution directive section
71+
- Entry point: `.devagent/core/agents/TaskPlanner.md`
72+
- Acceptance: Execution directive added
73+
8. `Update TaskExecutor.md` — Add execution directive section
74+
- Entry point: `.devagent/core/agents/TaskExecutor.md`
75+
- Acceptance: Execution directive added
76+
9. `Update TaskPromptBuilder.md` — Add execution directive section
77+
- Entry point: `.devagent/core/agents/TaskPromptBuilder.md`
78+
- Acceptance: Execution directive added
79+
10. `Update TechStackAgent.md` — Add execution directive section
80+
- Entry point: `.devagent/core/agents/TechStackAgent.md`
81+
- Acceptance: Execution directive added
82+
11. `Update UpdateConstitution.md` — Add execution directive section
83+
- Entry point: `.devagent/core/agents/UpdateConstitution.md`
84+
- Acceptance: Execution directive added
85+
12. `Update CodegenBackgroundAgent.md` — Add execution directive section
86+
- Entry point: `.devagent/core/agents/codegen/CodegenBackgroundAgent.md`
87+
- Note: Already has "Invocation assumption" line 7, integrate with execution directive
88+
- Acceptance: Execution directive added, invocation assumption preserved or merged
89+
- **Validation plan:** Grep check that all 12 files contain execution directive text
90+
91+
### Task 3: Test Execution Behavior
92+
93+
- **Objective:** Verify agents execute immediately instead of describing
94+
- **Dependencies:** Task 2 complete
95+
- **Subtasks:**
96+
1. `Test simple agent invocation` — Invoke #ResearchAgent or #TaskPlanner and verify it executes workflow
97+
- Test: Invoke agent with complete inputs, observe if it executes immediately or describes
98+
- Acceptance: Agent uses tools (read_file, write, etc.) without requesting approval
99+
2. `Test agent with missing inputs` — Invoke agent without required inputs, verify it pauses appropriately
100+
- Test: Invoke agent without required spec path or feature slug
101+
- Acceptance: Agent pauses and requests missing REQUIRED inputs (not optional ones)
102+
3. `Document behavior change` — Update feature hub README with test results
103+
- Entry point: `.devagent/features/2025-10-01_agent-execution-directive/README.md`
104+
- Acceptance: Test results documented, behavior change confirmed
105+
- **Validation plan:** Manual testing with 2-3 agents to confirm execution behavior change
106+
107+
## Risk Register
108+
109+
| Risk | Impact | Mitigation | Owner |
110+
| --- | --- | --- | --- |
111+
| Agents become too aggressive, execute destructive operations | Medium - data loss | Add safeguard note for destructive operations in directive | @jaruesink |
112+
| Directive placement inconsistent across agents | Low - cosmetic | Standardize placement in Task 1 before updates | @jaruesink |
113+
| Merge conflicts with restructure work | Medium - rework | Wait for restructure completion before executing | @jaruesink |
114+
| Directive doesn't change behavior | High - wasted effort | Test with one agent first, iterate directive text if needed | @jaruesink |
115+
116+
## Dependencies
117+
118+
**Upstream (Blocking This Work):**
119+
- Core-workspace-split restructure must complete first (agents move to `.devagent/core/agents/`)
120+
121+
**Downstream (Blocked By This Work):**
122+
- None - this enables all future agent work to be more autonomous
123+
124+
**Parallel Work:**
125+
- None - can execute independently after restructure completes
126+
127+
## Success Signals
128+
129+
- [ ] Execution directive standard defined and documented
130+
- [ ] All 12 agent files updated with execution directive
131+
- [ ] Agent template updated for future agents
132+
- [ ] Test confirms agents execute immediately instead of describing
133+
- [ ] No merge conflicts with restructure work
134+
- [ ] Behavior change documented
135+
136+
## Open Questions
137+
138+
| Question | Impact | Owner | Target Resolution |
139+
| --- | --- | --- | --- |
140+
| Should directive be same for all agents or customized? | Low - consistency | @jaruesink | Task 1 |
141+
| Do we need safeguards for destructive operations? | Medium - safety | @jaruesink | Task 1 or per-agent basis |
142+
| Should we version agent files after this change? | Low - documentation | @jaruesink | Post-implementation |
143+
144+
## Implementation Notes
145+
146+
- **Sequencing rationale:** Define standard first (Task 1), then bulk-update all agents (Task 2), then validate (Task 3)
147+
- **Timing:** Execute AFTER core-workspace-split merges to avoid conflicts
148+
- **Testing approach:** Test with 1-2 agents first to validate directive effectiveness before updating all 12
149+
- **Incremental commits:** Commit after each major task to enable rollback if directive doesn't work
150+
151+
## Next Steps
152+
153+
1. Wait for core-workspace-split to complete and merge
154+
2. Review this task plan with @jaruesink for approval
155+
3. Execute Task 1 to define execution directive standard
156+
4. Test directive with one agent before bulk update
157+
5. Execute Task 2 to update all agents
158+
6. Test and document behavior change
159+
160+
---
161+
162+
**Related Feature:** `.devagent/features/2025-10-01_agent-execution-directive/`
163+
**Blocked By:** `.devagent/features/2025-10-01_core-workspace-split/` completion
164+

0 commit comments

Comments
 (0)