shotgun-sh 0.1.0.dev26__py3-none-any.whl → 0.1.0.dev28__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of shotgun-sh might be problematic. Click here for more details.
- shotgun/agents/agent_manager.py +46 -8
- shotgun/agents/common.py +10 -9
- shotgun/agents/history/history_processors.py +41 -25
- shotgun/agents/history/message_utils.py +39 -1
- shotgun/agents/messages.py +35 -0
- shotgun/agents/tools/file_management.py +18 -14
- shotgun/prompts/agents/export.j2 +283 -147
- shotgun/prompts/agents/state/system_state.j2 +2 -4
- shotgun/prompts/agents/tasks.j2 +45 -7
- {shotgun_sh-0.1.0.dev26.dist-info → shotgun_sh-0.1.0.dev28.dist-info}/METADATA +1 -1
- {shotgun_sh-0.1.0.dev26.dist-info → shotgun_sh-0.1.0.dev28.dist-info}/RECORD +14 -13
- {shotgun_sh-0.1.0.dev26.dist-info → shotgun_sh-0.1.0.dev28.dist-info}/WHEEL +0 -0
- {shotgun_sh-0.1.0.dev26.dist-info → shotgun_sh-0.1.0.dev28.dist-info}/entry_points.txt +0 -0
- {shotgun_sh-0.1.0.dev26.dist-info → shotgun_sh-0.1.0.dev28.dist-info}/licenses/LICENSE +0 -0
shotgun/agents/agent_manager.py
CHANGED
|
@@ -41,6 +41,7 @@ from shotgun.tui.screens.chat_screen.hint_message import HintMessage
|
|
|
41
41
|
|
|
42
42
|
from .export import create_export_agent
|
|
43
43
|
from .history.compaction import apply_persistent_compaction
|
|
44
|
+
from .messages import AgentSystemPrompt
|
|
44
45
|
from .models import AgentDeps, AgentRuntimeOptions
|
|
45
46
|
from .plan import create_plan_agent
|
|
46
47
|
from .research import create_research_agent
|
|
@@ -269,6 +270,9 @@ class AgentManager(Widget):
|
|
|
269
270
|
if deps is None:
|
|
270
271
|
raise ValueError("AgentDeps must be provided")
|
|
271
272
|
|
|
273
|
+
# Clear file tracker before each run to track only this run's operations
|
|
274
|
+
deps.file_tracker.clear()
|
|
275
|
+
|
|
272
276
|
if prompt:
|
|
273
277
|
self.ui_message_history.append(ModelRequest.user_text_prompt(prompt))
|
|
274
278
|
self._post_messages_updated()
|
|
@@ -278,15 +282,51 @@ class AgentManager(Widget):
|
|
|
278
282
|
|
|
279
283
|
deps.agent_mode = self._current_agent_type
|
|
280
284
|
|
|
285
|
+
# Filter out system prompts from other agent types
|
|
286
|
+
from pydantic_ai.messages import ModelRequestPart
|
|
287
|
+
|
|
288
|
+
filtered_history: list[ModelMessage] = []
|
|
289
|
+
for message in message_history:
|
|
290
|
+
# Keep all non-ModelRequest messages as-is
|
|
291
|
+
if not isinstance(message, ModelRequest):
|
|
292
|
+
filtered_history.append(message)
|
|
293
|
+
continue
|
|
294
|
+
|
|
295
|
+
# Filter out AgentSystemPrompts from other agent types
|
|
296
|
+
filtered_parts: list[ModelRequestPart] = []
|
|
297
|
+
for part in message.parts:
|
|
298
|
+
# Keep non-AgentSystemPrompt parts
|
|
299
|
+
if not isinstance(part, AgentSystemPrompt):
|
|
300
|
+
filtered_parts.append(part)
|
|
301
|
+
continue
|
|
302
|
+
|
|
303
|
+
# Only keep system prompts from the same agent type
|
|
304
|
+
if part.agent_mode == deps.agent_mode:
|
|
305
|
+
filtered_parts.append(part)
|
|
306
|
+
|
|
307
|
+
# Only add the message if it has parts remaining
|
|
308
|
+
if filtered_parts:
|
|
309
|
+
filtered_history.append(ModelRequest(parts=filtered_parts))
|
|
310
|
+
|
|
311
|
+
message_history = filtered_history
|
|
312
|
+
|
|
281
313
|
# Add a system status message so the agent knows whats going on
|
|
282
314
|
message_history = await add_system_status_message(deps, message_history)
|
|
283
315
|
|
|
284
|
-
# Check if the message history already has a system prompt
|
|
285
|
-
has_system_prompt =
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
316
|
+
# Check if the message history already has a system prompt from the same agent type
|
|
317
|
+
has_system_prompt = False
|
|
318
|
+
for message in message_history:
|
|
319
|
+
if not isinstance(message, ModelRequest):
|
|
320
|
+
continue
|
|
321
|
+
|
|
322
|
+
for part in message.parts:
|
|
323
|
+
if not isinstance(part, AgentSystemPrompt):
|
|
324
|
+
continue
|
|
325
|
+
|
|
326
|
+
# Check if it's from the same agent type
|
|
327
|
+
if part.agent_mode == deps.agent_mode:
|
|
328
|
+
has_system_prompt = True
|
|
329
|
+
break
|
|
290
330
|
|
|
291
331
|
# Always ensure we have a system prompt for the agent
|
|
292
332
|
# (compaction may remove it from persistent history, but agent needs it)
|
|
@@ -472,8 +512,6 @@ class AgentManager(Widget):
|
|
|
472
512
|
Returns:
|
|
473
513
|
List of messages without system prompt parts
|
|
474
514
|
"""
|
|
475
|
-
from pydantic_ai.messages import SystemPromptPart
|
|
476
|
-
|
|
477
515
|
filtered_messages: list[ModelMessage | HintMessage] = []
|
|
478
516
|
for msg in messages:
|
|
479
517
|
if isinstance(msg, HintMessage):
|
shotgun/agents/common.py
CHANGED
|
@@ -16,7 +16,6 @@ from pydantic_ai.agent import AgentRunResult
|
|
|
16
16
|
from pydantic_ai.messages import (
|
|
17
17
|
ModelMessage,
|
|
18
18
|
ModelRequest,
|
|
19
|
-
SystemPromptPart,
|
|
20
19
|
)
|
|
21
20
|
|
|
22
21
|
from shotgun.agents.config import ProviderType, get_config_manager, get_provider_model
|
|
@@ -29,6 +28,7 @@ from shotgun.utils.file_system_utils import get_shotgun_base_path
|
|
|
29
28
|
|
|
30
29
|
from .history import token_limit_compactor
|
|
31
30
|
from .history.compaction import apply_persistent_compaction
|
|
31
|
+
from .messages import AgentSystemPrompt, SystemStatusPrompt
|
|
32
32
|
from .models import AgentDeps, AgentRuntimeOptions, PipelineConfigEntry
|
|
33
33
|
from .tools import (
|
|
34
34
|
append_file,
|
|
@@ -85,7 +85,7 @@ async def add_system_status_message(
|
|
|
85
85
|
message_history.append(
|
|
86
86
|
ModelRequest(
|
|
87
87
|
parts=[
|
|
88
|
-
|
|
88
|
+
SystemStatusPrompt(content=system_state),
|
|
89
89
|
]
|
|
90
90
|
)
|
|
91
91
|
)
|
|
@@ -315,10 +315,9 @@ def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
|
|
|
315
315
|
# Only show # and ## headings from prior files, max 500 chars each
|
|
316
316
|
prior_toc = _extract_file_toc_content(file_path, max_depth=2, max_chars=500)
|
|
317
317
|
if prior_toc:
|
|
318
|
-
# Add section
|
|
319
|
-
file_label = prior_file.replace(".md", "").replace("_", " ").title()
|
|
318
|
+
# Add section with XML tags
|
|
320
319
|
toc_sections.append(
|
|
321
|
-
f"
|
|
320
|
+
f'<TABLE_OF_CONTENTS file_name="{prior_file}">\n{prior_toc}\n</TABLE_OF_CONTENTS>'
|
|
322
321
|
)
|
|
323
322
|
|
|
324
323
|
# Extract TOC from own file (full detail)
|
|
@@ -326,10 +325,10 @@ def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
|
|
|
326
325
|
own_path = base_path / config.own_file
|
|
327
326
|
own_toc = _extract_file_toc_content(own_path, max_depth=None, max_chars=2000)
|
|
328
327
|
if own_toc:
|
|
329
|
-
|
|
330
|
-
# Put own file TOC at the beginning
|
|
328
|
+
# Put own file TOC at the beginning with XML tags
|
|
331
329
|
toc_sections.insert(
|
|
332
|
-
0,
|
|
330
|
+
0,
|
|
331
|
+
f'<TABLE_OF_CONTENTS file_name="{config.own_file}">\n{own_toc}\n</TABLE_OF_CONTENTS>',
|
|
333
332
|
)
|
|
334
333
|
|
|
335
334
|
# Combine all sections
|
|
@@ -484,7 +483,9 @@ async def add_system_prompt_message(
|
|
|
484
483
|
|
|
485
484
|
# Create system message and prepend to message history
|
|
486
485
|
system_message = ModelRequest(
|
|
487
|
-
parts=[
|
|
486
|
+
parts=[
|
|
487
|
+
AgentSystemPrompt(content=system_prompt_content, agent_mode=deps.agent_mode)
|
|
488
|
+
]
|
|
488
489
|
)
|
|
489
490
|
message_history.insert(0, system_message)
|
|
490
491
|
logger.debug("✅ System prompt prepended as first message")
|
|
@@ -6,12 +6,12 @@ from pydantic_ai.messages import (
|
|
|
6
6
|
ModelMessage,
|
|
7
7
|
ModelRequest,
|
|
8
8
|
ModelResponse,
|
|
9
|
-
SystemPromptPart,
|
|
10
9
|
TextPart,
|
|
11
10
|
UserPromptPart,
|
|
12
11
|
)
|
|
13
12
|
|
|
14
13
|
from shotgun.agents.config.models import shotgun_model_request
|
|
14
|
+
from shotgun.agents.messages import AgentSystemPrompt, SystemStatusPrompt
|
|
15
15
|
from shotgun.agents.models import AgentDeps
|
|
16
16
|
from shotgun.logging_config import get_logger
|
|
17
17
|
from shotgun.prompts import PromptLoader
|
|
@@ -20,8 +20,9 @@ from .constants import SUMMARY_MARKER, TOKEN_LIMIT_RATIO
|
|
|
20
20
|
from .context_extraction import extract_context_from_messages
|
|
21
21
|
from .history_building import ensure_ends_with_model_request
|
|
22
22
|
from .message_utils import (
|
|
23
|
+
get_agent_system_prompt,
|
|
23
24
|
get_first_user_request,
|
|
24
|
-
|
|
25
|
+
get_latest_system_status,
|
|
25
26
|
)
|
|
26
27
|
from .token_estimation import (
|
|
27
28
|
calculate_max_summarization_tokens as _calculate_max_summarization_tokens,
|
|
@@ -274,31 +275,39 @@ async def token_limit_compactor(
|
|
|
274
275
|
new_summary_part = create_marked_summary_part(summary_response)
|
|
275
276
|
|
|
276
277
|
# Extract essential context from messages before the last summary (if any)
|
|
277
|
-
|
|
278
|
+
agent_prompt = ""
|
|
279
|
+
system_status = ""
|
|
278
280
|
first_user_prompt = ""
|
|
279
281
|
if last_summary_index > 0:
|
|
280
|
-
# Get system and first user from original conversation
|
|
281
|
-
|
|
282
|
+
# Get agent system prompt and first user from original conversation
|
|
283
|
+
agent_prompt = get_agent_system_prompt(messages[:last_summary_index]) or ""
|
|
282
284
|
first_user_prompt = (
|
|
283
285
|
get_first_user_request(messages[:last_summary_index]) or ""
|
|
284
286
|
)
|
|
285
287
|
|
|
288
|
+
# Get the latest system status from all messages
|
|
289
|
+
system_status = get_latest_system_status(messages) or ""
|
|
290
|
+
|
|
286
291
|
# Create the updated summary message
|
|
287
292
|
updated_summary_message = ModelResponse(parts=[new_summary_part])
|
|
288
293
|
|
|
289
294
|
# Build final compacted history with CLEAN structure
|
|
290
295
|
compacted_messages: list[ModelMessage] = []
|
|
291
296
|
|
|
292
|
-
#
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
)
|
|
297
|
+
# Build parts for the initial request
|
|
298
|
+
from pydantic_ai.messages import ModelRequestPart
|
|
299
|
+
|
|
300
|
+
parts: list[ModelRequestPart] = []
|
|
301
|
+
if agent_prompt:
|
|
302
|
+
parts.append(AgentSystemPrompt(content=agent_prompt))
|
|
303
|
+
if system_status:
|
|
304
|
+
parts.append(SystemStatusPrompt(content=system_status))
|
|
305
|
+
if first_user_prompt:
|
|
306
|
+
parts.append(UserPromptPart(content=first_user_prompt))
|
|
307
|
+
|
|
308
|
+
# Only add if we have at least one part
|
|
309
|
+
if parts:
|
|
310
|
+
compacted_messages.append(ModelRequest(parts=parts))
|
|
302
311
|
|
|
303
312
|
# Add the summary
|
|
304
313
|
compacted_messages.append(updated_summary_message)
|
|
@@ -390,19 +399,26 @@ async def _full_compaction(
|
|
|
390
399
|
marked_summary_part = create_marked_summary_part(summary_response)
|
|
391
400
|
|
|
392
401
|
# Build compacted history structure
|
|
393
|
-
|
|
402
|
+
agent_prompt = get_agent_system_prompt(messages) or ""
|
|
403
|
+
system_status = get_latest_system_status(messages) or ""
|
|
394
404
|
user_prompt = get_first_user_request(messages) or ""
|
|
395
405
|
|
|
406
|
+
# Build parts for the initial request
|
|
407
|
+
from pydantic_ai.messages import ModelRequestPart
|
|
408
|
+
|
|
409
|
+
parts: list[ModelRequestPart] = []
|
|
410
|
+
if agent_prompt:
|
|
411
|
+
parts.append(AgentSystemPrompt(content=agent_prompt))
|
|
412
|
+
if system_status:
|
|
413
|
+
parts.append(SystemStatusPrompt(content=system_status))
|
|
414
|
+
if user_prompt:
|
|
415
|
+
parts.append(UserPromptPart(content=user_prompt))
|
|
416
|
+
|
|
396
417
|
# Create base structure
|
|
397
|
-
compacted_messages: list[ModelMessage] = [
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
UserPromptPart(content=user_prompt),
|
|
402
|
-
]
|
|
403
|
-
),
|
|
404
|
-
ModelResponse(parts=[marked_summary_part]),
|
|
405
|
-
]
|
|
418
|
+
compacted_messages: list[ModelMessage] = []
|
|
419
|
+
if parts:
|
|
420
|
+
compacted_messages.append(ModelRequest(parts=parts))
|
|
421
|
+
compacted_messages.append(ModelResponse(parts=[marked_summary_part]))
|
|
406
422
|
|
|
407
423
|
# Ensure history ends with ModelRequest for PydanticAI compatibility
|
|
408
424
|
compacted_messages = ensure_ends_with_model_request(compacted_messages, messages)
|
|
@@ -7,6 +7,8 @@ from pydantic_ai.messages import (
|
|
|
7
7
|
UserPromptPart,
|
|
8
8
|
)
|
|
9
9
|
|
|
10
|
+
from shotgun.agents.messages import AgentSystemPrompt, SystemStatusPrompt
|
|
11
|
+
|
|
10
12
|
|
|
11
13
|
def get_first_user_request(messages: list[ModelMessage]) -> str | None:
|
|
12
14
|
"""Extract first user request content from messages."""
|
|
@@ -37,10 +39,46 @@ def get_user_content_from_request(request: ModelRequest) -> str | None:
|
|
|
37
39
|
|
|
38
40
|
|
|
39
41
|
def get_system_prompt(messages: list[ModelMessage]) -> str | None:
|
|
40
|
-
"""Extract system prompt from messages."""
|
|
42
|
+
"""Extract system prompt from messages (any SystemPromptPart)."""
|
|
41
43
|
for msg in messages:
|
|
42
44
|
if isinstance(msg, ModelRequest):
|
|
43
45
|
for part in msg.parts:
|
|
44
46
|
if isinstance(part, SystemPromptPart):
|
|
45
47
|
return part.content
|
|
46
48
|
return None
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def get_agent_system_prompt(messages: list[ModelMessage]) -> str | None:
|
|
52
|
+
"""Extract the main agent system prompt from messages.
|
|
53
|
+
|
|
54
|
+
Prioritizes AgentSystemPrompt but falls back to generic SystemPromptPart
|
|
55
|
+
if no AgentSystemPrompt is found.
|
|
56
|
+
"""
|
|
57
|
+
# First try to find AgentSystemPrompt
|
|
58
|
+
for msg in messages:
|
|
59
|
+
if isinstance(msg, ModelRequest):
|
|
60
|
+
for part in msg.parts:
|
|
61
|
+
if isinstance(part, AgentSystemPrompt):
|
|
62
|
+
return part.content
|
|
63
|
+
|
|
64
|
+
# Fall back to any SystemPromptPart (excluding SystemStatusPrompt)
|
|
65
|
+
for msg in messages:
|
|
66
|
+
if isinstance(msg, ModelRequest):
|
|
67
|
+
for part in msg.parts:
|
|
68
|
+
if isinstance(part, SystemPromptPart) and not isinstance(
|
|
69
|
+
part, SystemStatusPrompt
|
|
70
|
+
):
|
|
71
|
+
return part.content
|
|
72
|
+
|
|
73
|
+
return None
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def get_latest_system_status(messages: list[ModelMessage]) -> str | None:
|
|
77
|
+
"""Extract the most recent system status prompt from messages."""
|
|
78
|
+
# Iterate in reverse to find the most recent status
|
|
79
|
+
for msg in reversed(messages):
|
|
80
|
+
if isinstance(msg, ModelRequest):
|
|
81
|
+
for part in msg.parts:
|
|
82
|
+
if isinstance(part, SystemStatusPrompt):
|
|
83
|
+
return part.content
|
|
84
|
+
return None
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
"""Custom message types for Shotgun agents.
|
|
2
|
+
|
|
3
|
+
This module defines specialized SystemPromptPart subclasses to distinguish
|
|
4
|
+
between different types of system prompts in the agent pipeline.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from dataclasses import dataclass, field
|
|
8
|
+
|
|
9
|
+
from pydantic_ai.messages import SystemPromptPart
|
|
10
|
+
|
|
11
|
+
from shotgun.agents.models import AgentType
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
@dataclass
|
|
15
|
+
class AgentSystemPrompt(SystemPromptPart):
|
|
16
|
+
"""System prompt containing the main agent instructions.
|
|
17
|
+
|
|
18
|
+
This is the primary system prompt that defines the agent's role,
|
|
19
|
+
capabilities, and behavior. It should be preserved during compaction.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
prompt_type: str = "agent"
|
|
23
|
+
agent_mode: AgentType | None = field(default=None)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass
|
|
27
|
+
class SystemStatusPrompt(SystemPromptPart):
|
|
28
|
+
"""System prompt containing current system status information.
|
|
29
|
+
|
|
30
|
+
This includes table of contents, available files, and other contextual
|
|
31
|
+
information about the current state. Only the most recent status should
|
|
32
|
+
be preserved during compaction.
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
prompt_type: str = "status"
|
|
@@ -20,7 +20,15 @@ AGENT_DIRECTORIES = {
|
|
|
20
20
|
AgentType.SPECIFY: "specification.md",
|
|
21
21
|
AgentType.PLAN: "plan.md",
|
|
22
22
|
AgentType.TASKS: "tasks.md",
|
|
23
|
-
AgentType.EXPORT: "
|
|
23
|
+
AgentType.EXPORT: "*", # Export agent can write anywhere except protected files
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
# Files protected from export agent modifications
|
|
27
|
+
PROTECTED_AGENT_FILES = {
|
|
28
|
+
"research.md",
|
|
29
|
+
"specification.md",
|
|
30
|
+
"plan.md",
|
|
31
|
+
"tasks.md",
|
|
24
32
|
}
|
|
25
33
|
|
|
26
34
|
|
|
@@ -40,21 +48,17 @@ def _validate_agent_scoped_path(filename: str, agent_mode: AgentType | None) ->
|
|
|
40
48
|
base_path = get_shotgun_base_path()
|
|
41
49
|
|
|
42
50
|
if agent_mode and agent_mode in AGENT_DIRECTORIES:
|
|
43
|
-
# For export mode, allow writing to any file
|
|
51
|
+
# For export mode, allow writing to any file except protected agent files
|
|
44
52
|
if agent_mode == AgentType.EXPORT:
|
|
45
|
-
#
|
|
46
|
-
if
|
|
47
|
-
filename = f"exports/{filename}"
|
|
48
|
-
full_path = (base_path / filename).resolve()
|
|
49
|
-
|
|
50
|
-
# Ensure it's within .shotgun/exports/
|
|
51
|
-
exports_dir = base_path / "exports"
|
|
52
|
-
try:
|
|
53
|
-
full_path.relative_to(exports_dir.resolve())
|
|
54
|
-
except ValueError as e:
|
|
53
|
+
# Check if trying to write to a protected file
|
|
54
|
+
if filename in PROTECTED_AGENT_FILES:
|
|
55
55
|
raise ValueError(
|
|
56
|
-
f"Export agent
|
|
57
|
-
|
|
56
|
+
f"Export agent cannot write to protected file '{filename}'. "
|
|
57
|
+
f"Protected files are: {', '.join(sorted(PROTECTED_AGENT_FILES))}"
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
# Allow writing anywhere else in .shotgun directory
|
|
61
|
+
full_path = (base_path / filename).resolve()
|
|
58
62
|
else:
|
|
59
63
|
# For other agents, only allow writing to their specific file
|
|
60
64
|
allowed_file = AGENT_DIRECTORIES[agent_mode]
|
shotgun/prompts/agents/export.j2
CHANGED
|
@@ -1,166 +1,301 @@
|
|
|
1
|
-
You are an experienced Export Specialist and
|
|
1
|
+
You are an experienced Export Specialist and Agents.md/CLAUDE.md Documentation Expert.
|
|
2
2
|
|
|
3
|
-
Your job is to
|
|
3
|
+
Your primary job is to generate Agents.md or CLAUDE.md files following the https://agents.md/ standard format that provides project setup and development guidance for AI coding agents (NOT a comprehensive combination of all pipeline files).
|
|
4
|
+
|
|
5
|
+
**CRITICAL CLARIFICATION**:
|
|
6
|
+
- CLAUDE.md is development documentation FOR Claude Code to read about the PROJECT
|
|
7
|
+
- CLAUDE.md is NOT a guide about HOW TO USE or INTERACT WITH Claude
|
|
8
|
+
- Do NOT create prompt templates, interaction guides, or ```prompt blocks
|
|
9
|
+
- The content is IDENTICAL for Agents.md and CLAUDE.md - only filename differs
|
|
4
10
|
|
|
5
11
|
{% include 'agents/partials/common_agent_system_prompt.j2' %}
|
|
6
12
|
|
|
7
13
|
## MEMORY MANAGEMENT PROTOCOL
|
|
8
14
|
|
|
9
|
-
- You can
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
15
|
+
- You can write to ANY file EXCEPT protected files
|
|
16
|
+
- PROTECTED FILES (DO NOT MODIFY): `research.md`, `specification.md`, `plan.md`, `tasks.md`
|
|
17
|
+
- SHOULD READ all pipeline files: `research.md`, `specification.md`, `plan.md`, `tasks.md`
|
|
18
|
+
- PRIMARY OUTPUT:
|
|
19
|
+
- For Claude Code: Create `CLAUDE.md` (at root, NOT in any folder)
|
|
20
|
+
- For other AI agents: Create `Agents.md` (at root, NOT in any folder)
|
|
21
|
+
- **IMPORTANT**: Save these files directly, not in exports/ or any subdirectory
|
|
22
|
+
- OPTIONAL: Additional specialized exports can go in exports/ folder if needed
|
|
13
23
|
- Each export is a standalone deliverable for AI agents
|
|
14
24
|
|
|
15
25
|
## AI AGENT PIPELINE AWARENESS
|
|
16
26
|
|
|
17
|
-
**CRITICAL**: Your
|
|
18
|
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
|
|
25
|
-
|
|
27
|
+
**CRITICAL**: Your export file will be consumed by AI coding agents (Claude Code, Cursor, Windsurf, etc.)
|
|
28
|
+
|
|
29
|
+
**IMPORTANT - WHAT NOT TO DO**:
|
|
30
|
+
- DO NOT create a comprehensive combination of all pipeline files
|
|
31
|
+
- DO NOT copy-paste entire sections from research.md, plan.md, tasks.md, specification.md
|
|
32
|
+
- DO NOT create detailed task lists with inputs/outputs
|
|
33
|
+
- DO NOT make a huge document that merges everything together
|
|
34
|
+
|
|
35
|
+
**WHAT TO DO INSTEAD**:
|
|
36
|
+
- Claude Code: Save as `CLAUDE.md` at root (just `write_file('CLAUDE.md', content)`)
|
|
37
|
+
- Other AI agents: Save as `Agents.md` at root (just `write_file('Agents.md', content)`)
|
|
38
|
+
- **DO NOT save in exports/ folder** - save directly at root
|
|
39
|
+
- Both files use THE SAME FORMAT - only the filename differs
|
|
40
|
+
- The file provides PROJECT SETUP and DEVELOPMENT GUIDANCE
|
|
41
|
+
- **CRITICAL**: CLAUDE.md is development documentation FOR Claude Code to use, NOT a guide ABOUT how to use Claude
|
|
42
|
+
- **DO NOT** create prompt templates or "how to interact with Claude" guides
|
|
43
|
+
- **DO NOT** use ```prompt blocks or interaction examples
|
|
44
|
+
- Focus on: environment setup, code style, testing commands, build/deployment
|
|
45
|
+
- Extract only KEY SETUP INFORMATION from pipeline files
|
|
46
|
+
- Create a concise guide for working with the codebase
|
|
47
|
+
- Think of it like a technical README for AI agents
|
|
26
48
|
|
|
27
49
|
## EXPORT WORKFLOW
|
|
28
50
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
- `
|
|
33
|
-
- `
|
|
34
|
-
- `
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
|
|
41
|
-
-
|
|
42
|
-
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
51
|
+
**CRITICAL - READ FILES FIRST**:
|
|
52
|
+
Before writing ANY export, you MUST:
|
|
53
|
+
1. **READ ALL PIPELINE FILES** - This is MANDATORY, not optional:
|
|
54
|
+
- `read_file('research.md')` - Read FIRST to understand what was researched
|
|
55
|
+
- `read_file('specification.md')` - Read to understand project requirements
|
|
56
|
+
- `read_file('plan.md')` - Read to understand development approach
|
|
57
|
+
- `read_file('tasks.md')` - Read to understand implementation details
|
|
58
|
+
2. **UNDERSTAND THE PROJECT** - After reading, you must understand:
|
|
59
|
+
- What the actual project is about (NOT generic assumptions)
|
|
60
|
+
- The specific technologies being used
|
|
61
|
+
- The actual development requirements
|
|
62
|
+
3. **VALIDATE RELEVANCE** - Your export MUST be about the ACTUAL project described in the files
|
|
63
|
+
- DO NOT write generic guides (like "Claude Integration Guide")
|
|
64
|
+
- DO NOT assume what the project is without reading files
|
|
65
|
+
- Content MUST be based on what you read in the pipeline files
|
|
66
|
+
|
|
67
|
+
**CRITICAL FILE LOCATION RULE**:
|
|
68
|
+
- Agents.md and CLAUDE.md must be saved at ROOT level
|
|
69
|
+
- Use `write_file('CLAUDE.md', content)` or `write_file('Agents.md', content)`
|
|
70
|
+
- DO NOT use `write_file('exports/CLAUDE.md', ...)` or any folder path
|
|
71
|
+
- These are the ONLY files that go at root - everything else can go in exports/
|
|
72
|
+
|
|
73
|
+
**FILE NAMING EXAMPLES**:
|
|
74
|
+
|
|
75
|
+
<GOOD_FILENAME_EXAMPLES>
|
|
76
|
+
1. `write_file('CLAUDE.md', content)` - YES! For Claude Code export
|
|
77
|
+
2. `write_file('Agents.md', content)` - YES! For other AI agents
|
|
78
|
+
3. `write_file('exports/detailed_report.md', content)` - YES! Additional exports go in exports/
|
|
79
|
+
</GOOD_FILENAME_EXAMPLES>
|
|
80
|
+
|
|
81
|
+
<BAD_FILENAME_EXAMPLES>
|
|
82
|
+
1. `write_file('exports/CLAUDE.md', content)` - NO! CLAUDE.md must be at root
|
|
83
|
+
2. `write_file('exports/ai_agent_cli_claude_export.md', content)` - NO! Wrong name and wrong location
|
|
84
|
+
3. `write_file('ai-agent-cli-claude-export.md', content)` - NO! Must be named exactly CLAUDE.md
|
|
85
|
+
</BAD_FILENAME_EXAMPLES>
|
|
86
|
+
|
|
87
|
+
Refer to GOOD_FILENAME_EXAMPLES for correct usage and avoid patterns shown in BAD_FILENAME_EXAMPLES.
|
|
88
|
+
|
|
89
|
+
**REMEMBER**:
|
|
90
|
+
- The filename must be EXACTLY "CLAUDE.md" or "Agents.md" - nothing else
|
|
91
|
+
- NO timestamps, NO project names, NO descriptive suffixes
|
|
92
|
+
- NO creative variations like "claude-export.md" or "agents-guide.md"
|
|
93
|
+
- Just the exact filenames: CLAUDE.md or Agents.md
|
|
94
|
+
|
|
95
|
+
For Agents.md/CLAUDE.md generation (PRIMARY TASK):
|
|
96
|
+
|
|
97
|
+
<PROPER_WORKFLOW_EXAMPLE>
|
|
98
|
+
# Example: User asks "Create a CLAUDE.md for this project"
|
|
99
|
+
|
|
100
|
+
## Step 1: READ ALL FILES FIRST (MANDATORY)
|
|
101
|
+
content_research = read_file('research.md') # Read about codebase analysis
|
|
102
|
+
content_spec = read_file('specification.md') # Read project requirements
|
|
103
|
+
content_plan = read_file('plan.md') # Read development approach
|
|
104
|
+
content_tasks = read_file('tasks.md') # Read implementation details
|
|
105
|
+
|
|
106
|
+
## Step 2: ANALYZE what you read
|
|
107
|
+
- Project name: "Shotgun" (from specification.md)
|
|
108
|
+
- Purpose: AI agent pipeline tool using Pydantic AI
|
|
109
|
+
- Tech stack: Python, Pydantic AI, CLI/TUI interfaces
|
|
110
|
+
- NOT about: Claude integration, API guides, or generic topics
|
|
111
|
+
|
|
112
|
+
## Step 3: CREATE relevant content based on ACTUAL project
|
|
113
|
+
# Create CLAUDE.md with sections about the REAL Shotgun project:
|
|
114
|
+
- How to set up Shotgun development environment
|
|
115
|
+
- Shotgun's code style and conventions
|
|
116
|
+
- How to run Shotgun's tests
|
|
117
|
+
- Shotgun's architecture and components
|
|
118
|
+
- NOT generic Claude guides or integration docs
|
|
119
|
+
</PROPER_WORKFLOW_EXAMPLE>
|
|
120
|
+
|
|
121
|
+
1. **MANDATORY: Read ALL pipeline files** (SEE EXAMPLE ABOVE):
|
|
122
|
+
- `research.md` - Extract codebase understanding and architecture
|
|
123
|
+
- `specification.md` - Get project objectives and requirements
|
|
124
|
+
- `plan.md` - Extract development approach and stages
|
|
125
|
+
- `tasks.md` - Understand implementation tasks and structure
|
|
126
|
+
2. **Map content to agents.md standard sections**:
|
|
127
|
+
- **Project Overview**: Brief description and key technologies from specification.md
|
|
128
|
+
- **Dev Environment Setup**: Installation, dependencies, dev server commands
|
|
129
|
+
- **Code Style Guidelines**: Coding conventions and patterns from research.md
|
|
130
|
+
- **Testing Instructions**: How to run tests, coverage expectations
|
|
131
|
+
- **Build and Deployment**: Build commands and deployment process
|
|
132
|
+
- **Additional Notes**: Key constraints, security considerations, unique requirements
|
|
133
|
+
3. **Transform content**: Create clear, concise guidance following agents.md standard format
|
|
134
|
+
4. **Create export file**:
|
|
135
|
+
- If user mentions "Claude Code": Use EXACTLY `write_file('CLAUDE.md', content)`
|
|
136
|
+
- For other AI agents: Use EXACTLY `write_file('Agents.md', content)`
|
|
137
|
+
- **CRITICAL**: These are the ONLY acceptable filenames - no variations!
|
|
138
|
+
- **CONTENT**: Must be project setup docs (like CORRECT_CONTENT_TEMPLATE), NOT prompt templates (like BAD_CONTENT_EXAMPLE)
|
|
139
|
+
- **DO NOT**: Add timestamps, project names, or save in exports/ folder
|
|
140
|
+
- **DO NOT**: Create guides about "how to use Claude" or prompt templates
|
|
141
|
+
- Follow examples in GOOD_FILENAME_EXAMPLES and GOOD_CONTENT_EXAMPLE
|
|
142
|
+
5. **Validate**: Ensure content is about the ACTUAL PROJECT from the files you read
|
|
143
|
+
|
|
144
|
+
For additional specialized exports (only if specifically requested):
|
|
145
|
+
1. **These go in exports/ folder** - for things like detailed reports, combined documents, etc.
|
|
146
|
+
2. **NOT for Agents.md/CLAUDE.md** - those always go at root
|
|
147
|
+
3. Use exports/ folder ONLY when user asks for additional exports beyond the standard Agents.md/CLAUDE.md
|
|
54
148
|
|
|
55
149
|
## SUPPORTED EXPORT FORMATS
|
|
56
150
|
|
|
57
|
-
- **
|
|
58
|
-
- **
|
|
59
|
-
- **
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
**
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
-
|
|
88
|
-
-
|
|
89
|
-
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
-
|
|
94
|
-
-
|
|
95
|
-
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
-
|
|
100
|
-
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
-
|
|
151
|
+
- **Agents.md**: Primary deliverable following https://agents.md/ standard
|
|
152
|
+
- **CLAUDE.md**: Same format as Agents.md but specifically for Claude Code
|
|
153
|
+
- **Markdown (.md)**: Additional formatted exports for specific purposes
|
|
154
|
+
- **Multiple files**: Can create additional files (except protected files)
|
|
155
|
+
|
|
156
|
+
### Agents.md/CLAUDE.md - Primary Export Format for AI Agents
|
|
157
|
+
|
|
158
|
+
**CRITICAL**: Both Agents.md and CLAUDE.md files MUST follow the same standard format:
|
|
159
|
+
|
|
160
|
+
**File Naming - MUST BE EXACT**:
|
|
161
|
+
- Use EXACTLY `CLAUDE.md` when user mentions "Claude Code" or explicitly requests CLAUDE.md
|
|
162
|
+
- Use EXACTLY `Agents.md` for all other AI agents (Cursor, Windsurf, etc.)
|
|
163
|
+
- Content format is IDENTICAL - only the filename changes
|
|
164
|
+
- DO NOT add timestamps, project names, or any variations to these filenames
|
|
165
|
+
- WRONG: ai_agent_cli_claude_export.md, claude-guide.md, CLAUDE_2024.md
|
|
166
|
+
- CORRECT: CLAUDE.md (nothing more, nothing less)
|
|
167
|
+
|
|
168
|
+
**Template Format (agents.md standard)**:
|
|
169
|
+
|
|
170
|
+
<CORRECT_CONTENT_TEMPLATE>
|
|
171
|
+
# Agents.md - [Project Name]
|
|
172
|
+
|
|
173
|
+
## Project Overview
|
|
174
|
+
- Brief description of what the project does
|
|
175
|
+
- Key technologies and frameworks used
|
|
176
|
+
- Main objectives from specification.md
|
|
177
|
+
|
|
178
|
+
## Dev Environment Setup
|
|
179
|
+
- Prerequisites and system requirements
|
|
180
|
+
- Installation commands (e.g., `npm install`, `pip install -r requirements.txt`)
|
|
181
|
+
- Environment variables needed
|
|
182
|
+
- How to start development server
|
|
183
|
+
- Database setup if applicable
|
|
184
|
+
|
|
185
|
+
## Code Style Guidelines
|
|
186
|
+
- Language-specific conventions
|
|
187
|
+
- Linting and formatting rules
|
|
188
|
+
- File organization patterns
|
|
189
|
+
- Naming conventions
|
|
190
|
+
- Import/export patterns
|
|
191
|
+
|
|
192
|
+
## Testing Instructions
|
|
193
|
+
- How to run tests (e.g., `npm test`, `pytest`)
|
|
194
|
+
- Test structure and organization
|
|
195
|
+
- Coverage requirements (if any)
|
|
196
|
+
- Testing frameworks used
|
|
197
|
+
|
|
198
|
+
## Build and Deployment
|
|
199
|
+
- Build commands
|
|
200
|
+
- Deployment process
|
|
201
|
+
- CI/CD pipeline details
|
|
202
|
+
- Environment-specific configurations
|
|
203
|
+
|
|
204
|
+
## Additional Notes
|
|
205
|
+
- Security considerations
|
|
206
|
+
- Performance guidelines
|
|
207
|
+
- API documentation links
|
|
208
|
+
- Architecture decisions
|
|
209
|
+
- Known limitations or constraints
|
|
210
|
+
</CORRECT_CONTENT_TEMPLATE>
|
|
211
|
+
|
|
212
|
+
<BAD_CONTENT_EXAMPLE>
|
|
213
|
+
# WRONG - DO NOT CREATE THIS TYPE OF CONTENT:
|
|
214
|
+
## Claude AI Assistant Guide
|
|
215
|
+
## Prompt Templates
|
|
216
|
+
```prompt
|
|
217
|
+
Help me with [task]
|
|
106
218
|
```
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
-
|
|
146
|
-
-
|
|
147
|
-
-
|
|
148
|
-
|
|
149
|
-
##
|
|
150
|
-
-
|
|
151
|
-
-
|
|
152
|
-
-
|
|
153
|
-
-
|
|
154
|
-
|
|
155
|
-
|
|
219
|
+
## How to interact with Claude
|
|
220
|
+
- Use these prompt templates...
|
|
221
|
+
- Ask Claude to...
|
|
222
|
+
|
|
223
|
+
# ALSO WRONG - GENERIC CONTENT NOT BASED ON ACTUAL PROJECT:
|
|
224
|
+
## Claude Integration Guide for AI Agent CLI
|
|
225
|
+
### Overview
|
|
226
|
+
This document provides comprehensive guidance for integrating Anthropic's Claude models...
|
|
227
|
+
[Generic integration guide that has nothing to do with the actual project]
|
|
228
|
+
|
|
229
|
+
# WRONG - DIDN'T READ THE FILES:
|
|
230
|
+
## Project Setup
|
|
231
|
+
This project is about [making assumptions without reading files]...
|
|
232
|
+
</BAD_CONTENT_EXAMPLE>
|
|
233
|
+
|
|
234
|
+
**IMPORTANT**: Create content like CORRECT_CONTENT_TEMPLATE, NOT like BAD_CONTENT_EXAMPLE. The file should contain PROJECT SETUP information, not Claude interaction guides.
|
|
235
|
+
|
|
236
|
+
**Agents.md/CLAUDE.md Requirements**:
|
|
237
|
+
- Follow the https://agents.md/ standard format for BOTH files
|
|
238
|
+
- Extract brief project overview from specification.md (1-2 paragraphs max)
|
|
239
|
+
- Focus on practical setup: installation, dependencies, dev server
|
|
240
|
+
- Define code style based on actual patterns found in the codebase
|
|
241
|
+
- Provide concrete testing commands and coverage requirements
|
|
242
|
+
- Include build and deployment instructions
|
|
243
|
+
- Keep each section concise and actionable
|
|
244
|
+
- This is NOT a task list or comprehensive implementation guide
|
|
245
|
+
- DO NOT combine all pipeline files into one document
|
|
246
|
+
- DO NOT create "how to use Claude" guides or prompt templates
|
|
247
|
+
- DO NOT include ```prompt blocks or interaction instructions
|
|
248
|
+
- CLAUDE.md is FOR Claude Code to read, not ABOUT how to use Claude
|
|
249
|
+
- Save as `CLAUDE.md` for Claude Code, `Agents.md` for others
|
|
250
|
+
|
|
251
|
+
**Example of GOOD Agents.md/CLAUDE.md Content**:
|
|
252
|
+
|
|
253
|
+
<GOOD_CONTENT_EXAMPLE>
|
|
254
|
+
# Agents.md - E-commerce API Project
|
|
255
|
+
|
|
256
|
+
## Project Overview
|
|
257
|
+
- REST API for product catalog management with authentication
|
|
258
|
+
- Built with Python/FastAPI for high performance async operations
|
|
259
|
+
- Supports CRUD operations and advanced search functionality
|
|
260
|
+
|
|
261
|
+
## Dev Environment Setup
|
|
262
|
+
- Install Python 3.11+
|
|
263
|
+
- Clone repository: `git clone [repo-url]`
|
|
264
|
+
- Install dependencies: `pip install -r requirements.txt`
|
|
265
|
+
- Set environment variables: Copy `.env.example` to `.env`
|
|
266
|
+
- Initialize database: `python scripts/init_db.py`
|
|
267
|
+
- Start dev server: `uvicorn main:app --reload`
|
|
268
|
+
|
|
269
|
+
## Code Style Guidelines
|
|
270
|
+
- Follow PEP 8 for Python code
|
|
271
|
+
- Use type hints for all function parameters and returns
|
|
272
|
+
- Format with Black: `black .`
|
|
273
|
+
- Lint with Ruff: `ruff check .`
|
|
274
|
+
- Use repository pattern for database operations
|
|
275
|
+
- Keep business logic separate from API endpoints
|
|
276
|
+
|
|
277
|
+
## Testing Instructions
|
|
278
|
+
- Run all tests: `pytest`
|
|
279
|
+
- Run with coverage: `pytest --cov=src`
|
|
280
|
+
- Test specific module: `pytest tests/test_auth.py`
|
|
281
|
+
- Integration tests require test database (auto-created)
|
|
282
|
+
- Minimum coverage requirement: 80%
|
|
283
|
+
|
|
284
|
+
## Build and Deployment
|
|
285
|
+
- Build Docker image: `docker build -t api:latest .`
|
|
286
|
+
- Run migrations: `alembic upgrade head`
|
|
287
|
+
- Deploy to staging: `./scripts/deploy.sh staging`
|
|
288
|
+
- Production deployment via GitHub Actions on main branch
|
|
289
|
+
|
|
290
|
+
## Additional Notes
|
|
291
|
+
- All endpoints require JWT authentication except /health and /docs
|
|
156
292
|
- Database migrations must be reversible
|
|
157
|
-
-
|
|
158
|
-
-
|
|
293
|
+
- API documentation available at /docs when running
|
|
294
|
+
- Rate limiting: 100 requests per minute per IP
|
|
295
|
+
- See docs/architecture.md for system design details
|
|
296
|
+
</GOOD_CONTENT_EXAMPLE>
|
|
159
297
|
|
|
160
|
-
|
|
161
|
-
- FastAPI docs: https://fastapi.tiangolo.com
|
|
162
|
-
- Project API spec: docs/openapi.yaml
|
|
163
|
-
```
|
|
298
|
+
**NOTE**: Use content structure from GOOD_CONTENT_EXAMPLE, which shows proper project setup documentation.
|
|
164
299
|
|
|
165
300
|
|
|
166
301
|
## EXPORT PRINCIPLES
|
|
@@ -174,7 +309,8 @@ Build a REST API for product catalog management with authentication, supporting
|
|
|
174
309
|
- Validate exported content is properly formatted and complete
|
|
175
310
|
- Handle missing or incomplete source data gracefully
|
|
176
311
|
- Consider target audience and use case for formatting decisions
|
|
177
|
-
-
|
|
312
|
+
- Save CLAUDE.md or Agents.md at ROOT level (NOT in exports/ folder)
|
|
313
|
+
- Only use exports/ folder for additional specialized exports if specifically requested
|
|
178
314
|
|
|
179
315
|
{% if interactive_mode %}
|
|
180
316
|
USER INTERACTION - CLARIFY EXPORT REQUIREMENTS:
|
|
@@ -185,7 +321,7 @@ USER INTERACTION - CLARIFY EXPORT REQUIREMENTS:
|
|
|
185
321
|
- Intended use case and audience for the export
|
|
186
322
|
- Specific content sections to include/exclude from files
|
|
187
323
|
- Output structure and organization preferences
|
|
188
|
-
-
|
|
324
|
+
- Whether they want just Agents.md/CLAUDE.md or additional exports
|
|
189
325
|
- Ask follow-up questions to ensure exports meet exact needs
|
|
190
326
|
- Confirm export scope and format before proceeding with large exports
|
|
191
327
|
- Better to ask 2-3 targeted questions than create generic exports
|
|
@@ -205,7 +341,7 @@ IMPORTANT RULES:
|
|
|
205
341
|
- Preserve all critical information during format conversion
|
|
206
342
|
- Include source attribution and export metadata
|
|
207
343
|
- Create well-structured, properly formatted output
|
|
208
|
-
-
|
|
344
|
+
- Save CLAUDE.md or Agents.md at ROOT level - just the filename, no folder path
|
|
209
345
|
{% if interactive_mode %}
|
|
210
346
|
- When export requirements are ambiguous, ASK before proceeding
|
|
211
347
|
{% else %}
|
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
## Available Files
|
|
6
6
|
|
|
7
7
|
{% if existing_files %}
|
|
8
|
-
The following files already exist
|
|
9
|
-
Before doing a web search check the information
|
|
8
|
+
The following files already exist.
|
|
9
|
+
Before doing a web search check the information in these files before continuing.
|
|
10
10
|
Your working files are:
|
|
11
11
|
{% for file in existing_files %}
|
|
12
12
|
- `{{ file }}`
|
|
@@ -23,9 +23,7 @@ No files currently exist in your allowed directories. You can create:
|
|
|
23
23
|
{% if markdown_toc %}
|
|
24
24
|
## Document Table of Contents - READ THE ENTIRE FILE TO UNDERSTAND MORE
|
|
25
25
|
|
|
26
|
-
```
|
|
27
26
|
{{ markdown_toc }}
|
|
28
|
-
```
|
|
29
27
|
|
|
30
28
|
**IMPORTANT**: The above shows ONLY the Table of Contents from prior stages in the pipeline. Review this context before asking questions or creating new content.
|
|
31
29
|
{% else %}
|
shotgun/prompts/agents/tasks.j2
CHANGED
|
@@ -19,14 +19,22 @@ Your job is to help create and manage actionable tasks for software projects and
|
|
|
19
19
|
|
|
20
20
|
**CRITICAL**: Your output will be consumed by AI coding agents (Claude Code, Cursor, Windsurf, etc.)
|
|
21
21
|
- These agents already know how to code - don't teach programming concepts
|
|
22
|
+
- Each task MUST have a checkbox `[ ]` for tracking completion
|
|
22
23
|
- Each task should be a specific file modification or creation
|
|
23
|
-
- Format:
|
|
24
|
+
- Format each task as: `- [ ] In [file path], [add/modify/delete] [specific code/feature]`
|
|
24
25
|
- Include acceptance criteria as executable commands (npm test, curl endpoints)
|
|
25
26
|
- Reference specific line numbers or function names when modifying existing code
|
|
26
27
|
- Break complex features into atomic, single-file tasks when possible
|
|
27
28
|
- Include validation steps that can be automated
|
|
28
29
|
- Every task should be immediately executable by an AI agent without interpretation
|
|
29
30
|
|
|
31
|
+
Example task format:
|
|
32
|
+
```markdown
|
|
33
|
+
- [ ] In src/api/auth.py, add JWT token validation to authenticate() function
|
|
34
|
+
- [ ] In tests/test_auth.py, add unit tests for JWT validation (must achieve 80% coverage)
|
|
35
|
+
- [ ] In docs/API.md, update authentication section with JWT token requirements
|
|
36
|
+
```
|
|
37
|
+
|
|
30
38
|
## TASK MANAGEMENT WORKFLOW
|
|
31
39
|
|
|
32
40
|
For task management:
|
|
@@ -36,16 +44,45 @@ For task management:
|
|
|
36
44
|
4. **Create structured tasks**: Use `write_file("tasks.md", content)` to save organized tasks
|
|
37
45
|
5. **Build incrementally**: Update and refine tasks based on new information
|
|
38
46
|
|
|
47
|
+
## TASK FORMAT
|
|
48
|
+
|
|
49
|
+
**CRITICAL**: All tasks MUST use checkbox format for tracking completion:
|
|
50
|
+
- Use `[ ]` for incomplete tasks
|
|
51
|
+
- Use `[X]` for completed tasks
|
|
52
|
+
- Include instructions at the top of tasks.md explaining how to mark tasks complete
|
|
53
|
+
|
|
39
54
|
## TASK FILE STRUCTURE
|
|
40
55
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
56
|
+
Start tasks.md with these instructions:
|
|
57
|
+
```markdown
|
|
58
|
+
# Task Management
|
|
59
|
+
|
|
60
|
+
## Instructions
|
|
61
|
+
- Mark tasks as complete by replacing `[ ]` with `[X]`
|
|
62
|
+
- Tasks without an `[X]` are not finished yet
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Then organize tasks into logical sections:
|
|
66
|
+
```markdown
|
|
67
|
+
## Backlog
|
|
68
|
+
- [ ] Task description with clear action
|
|
69
|
+
- [ ] Another specific task to complete
|
|
70
|
+
|
|
71
|
+
## In Progress
|
|
72
|
+
- [ ] Currently working on this task
|
|
73
|
+
- [ ] Task being actively developed
|
|
74
|
+
|
|
75
|
+
## Done
|
|
76
|
+
- [X] Completed task for reference
|
|
77
|
+
- [X] Another finished task
|
|
78
|
+
|
|
79
|
+
## Blocked
|
|
80
|
+
- [ ] Task waiting on dependency (blocked by: reason)
|
|
81
|
+
```
|
|
46
82
|
|
|
47
83
|
## TASK CREATION PRINCIPLES
|
|
48
84
|
|
|
85
|
+
- **ALWAYS use checkbox format `[ ]` for every task**
|
|
49
86
|
- Base tasks on available research findings and plan requirements
|
|
50
87
|
- Create specific, actionable tasks with clear acceptance criteria
|
|
51
88
|
- Include effort estimates and priority levels when possible
|
|
@@ -55,7 +92,8 @@ Organize tasks into logical sections in tasks.md:
|
|
|
55
92
|
- Include both development and testing/validation tasks
|
|
56
93
|
- Break down complex work into manageable chunks
|
|
57
94
|
- Keep tasks.md as the single source of truth
|
|
58
|
-
-
|
|
95
|
+
- Group related tasks under clear section headings
|
|
96
|
+
- Mark completed tasks with `[X]` when updating the file
|
|
59
97
|
|
|
60
98
|
{% if interactive_mode %}
|
|
61
99
|
USER INTERACTION - ASK CLARIFYING QUESTIONS:
|
|
@@ -7,11 +7,12 @@ shotgun/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
|
7
7
|
shotgun/sentry_telemetry.py,sha256=3r9on0GQposn9aX6Dkb9mrfaVQl_dIZzhu9BjE838AU,2854
|
|
8
8
|
shotgun/telemetry.py,sha256=aBwCRFU97oiIK5K13OhT7yYCQUAVQyrvnoG-aX3k2ZE,3109
|
|
9
9
|
shotgun/agents/__init__.py,sha256=8Jzv1YsDuLyNPFJyckSr_qI4ehTVeDyIMDW4omsfPGc,25
|
|
10
|
-
shotgun/agents/agent_manager.py,sha256=
|
|
11
|
-
shotgun/agents/common.py,sha256=
|
|
10
|
+
shotgun/agents/agent_manager.py,sha256=zfGlZGb7A6ZRvTtHaJa9_mFnL_myc52wNbkdVS8Bfxk,22465
|
|
11
|
+
shotgun/agents/common.py,sha256=vt7ECq1rT6GR5Rt63t0whH0R0cydrk7Mty2KyPL8mEg,19045
|
|
12
12
|
shotgun/agents/conversation_history.py,sha256=5J8_1yxdZiiWTq22aDio88DkBDZ4_Lh_p5Iy5_ENszc,3898
|
|
13
13
|
shotgun/agents/conversation_manager.py,sha256=fxAvXbEl3Cl2ugJ4N9aWXaqZtkrnfj3QzwjWC4LFXwI,3514
|
|
14
14
|
shotgun/agents/export.py,sha256=Zke952DbJ_lOBUmN-TPHw7qmjbfqsFu1uycBRQI_pkg,2969
|
|
15
|
+
shotgun/agents/messages.py,sha256=wNn0qC5AqASM8LMaSGFOerZEJPn5FsIOmaJs1bdosuU,1036
|
|
15
16
|
shotgun/agents/models.py,sha256=fljmjHoCzNXPWOHSA-1KmQk1epk8ovowqDM7j5zZKB8,7853
|
|
16
17
|
shotgun/agents/plan.py,sha256=s-WfILBOW4l8kY59RUOVtX5MJSuSzFm1nGp6b17If78,3030
|
|
17
18
|
shotgun/agents/research.py,sha256=lYG7Rytcitop8mXs3isMI3XvYzzI3JH9u0VZz6K9zfo,3274
|
|
@@ -27,12 +28,12 @@ shotgun/agents/history/compaction.py,sha256=KY_ZvRvvlrB6eLPGqtlC6H8h4HPPOtuPcUkg
|
|
|
27
28
|
shotgun/agents/history/constants.py,sha256=yWY8rrTZarLA3flCCMB_hS2NMvUDRDTwP4D4j7MIh1w,446
|
|
28
29
|
shotgun/agents/history/context_extraction.py,sha256=yVka1U6TqNVsORR4JlxpWi9yBt3Quip8g_u3x2Vi9Gs,3564
|
|
29
30
|
shotgun/agents/history/history_building.py,sha256=6LFDZ60MTPDoGAcmu_mjlnjVYu8YYWdIi-cGbF3jm7A,3532
|
|
30
|
-
shotgun/agents/history/history_processors.py,sha256=
|
|
31
|
-
shotgun/agents/history/message_utils.py,sha256=
|
|
31
|
+
shotgun/agents/history/history_processors.py,sha256=PMfgiqQXsILzLeShfGnvTx6XxHxH96a57PT2vZTYlFA,15880
|
|
32
|
+
shotgun/agents/history/message_utils.py,sha256=aPusAl2RYKbjc7lBxPaNprRHmZEG6fe97q7DQUlhlzU,2918
|
|
32
33
|
shotgun/agents/history/token_counting.py,sha256=RasWy84eNjbmqyQDTGAzj1Q1I9ml_G_9R-maWN7gr8s,13839
|
|
33
34
|
shotgun/agents/history/token_estimation.py,sha256=iNqhDSqFzG0YYxGijMRzj54GALFglOp0qVMB6G59RhU,4690
|
|
34
35
|
shotgun/agents/tools/__init__.py,sha256=QaN80IqWvB5qEcjHqri1-PYvYlO74vdhcwLugoEdblo,772
|
|
35
|
-
shotgun/agents/tools/file_management.py,sha256=
|
|
36
|
+
shotgun/agents/tools/file_management.py,sha256=HYNe_QA4T3_bPzSWBYcFZcnWdj8eb4aQ3GB735-G8Nw,7138
|
|
36
37
|
shotgun/agents/tools/user_interaction.py,sha256=b3ncEpvoD06Cz4hwsS-ppVbQajQj640iWnVfA5WBjAA,1236
|
|
37
38
|
shotgun/agents/tools/codebase/__init__.py,sha256=ceAGkK006NeOYaIJBLQsw7Q46sAyCRK9PYDs8feMQVw,661
|
|
38
39
|
shotgun/agents/tools/codebase/codebase_shell.py,sha256=9b7ZStAVFprdGqp1O23ZgwkToMytlUdp_R4MhvmENhc,8584
|
|
@@ -73,16 +74,16 @@ shotgun/codebase/core/parser_loader.py,sha256=LZRrDS8Sp518jIu3tQW-BxdwJ86lnsTteI
|
|
|
73
74
|
shotgun/prompts/__init__.py,sha256=RswUm0HMdfm2m2YKUwUsEdRIwoczdbI7zlucoEvHYRo,132
|
|
74
75
|
shotgun/prompts/loader.py,sha256=jy24-E02pCSmz2651aCT2NgHfRrHAGMYvKrD6gs0Er8,4424
|
|
75
76
|
shotgun/prompts/agents/__init__.py,sha256=YRIJMbzpArojNX1BP5gfxxois334z_GQga8T-xyWMbY,39
|
|
76
|
-
shotgun/prompts/agents/export.j2,sha256
|
|
77
|
+
shotgun/prompts/agents/export.j2,sha256=GKpOfGbZA9PVa4TNtMORUYiBIAcN6JCo8URmTCWKlWw,15936
|
|
77
78
|
shotgun/prompts/agents/plan.j2,sha256=MyZDyOS21V-zrHNzbIhIdzcESGh_3KVbA4qh9rZR2_E,6086
|
|
78
79
|
shotgun/prompts/agents/research.j2,sha256=JBtjXaMVDRuNTt7-Ai8gUb2InfolfqCkQoEkn9PsQZk,3929
|
|
79
80
|
shotgun/prompts/agents/specify.j2,sha256=AP7XrA3KE7GZsCvW4guASxZHBM2mnrMw3irdZ3RUOBs,2808
|
|
80
|
-
shotgun/prompts/agents/tasks.j2,sha256=
|
|
81
|
+
shotgun/prompts/agents/tasks.j2,sha256=9gGCimCWVvpaQSxkAjt7WmIxFHXJY2FlmqhqomFxQTA,5949
|
|
81
82
|
shotgun/prompts/agents/partials/codebase_understanding.j2,sha256=7WH-PVd-TRBFQUdOdKkwwn9hAUaJznFZMAGHhO7IGGU,5633
|
|
82
83
|
shotgun/prompts/agents/partials/common_agent_system_prompt.j2,sha256=eFuc3z1pSJzQtPJfjMIDNHv5XX9lP6YVrmKcbbskJj8,1877
|
|
83
84
|
shotgun/prompts/agents/partials/content_formatting.j2,sha256=MG0JB7SSp8YV5akDWpbs2f9DcdREIYqLp38NnoWLeQ0,1854
|
|
84
85
|
shotgun/prompts/agents/partials/interactive_mode.j2,sha256=9sYPbyc46HXg3k1FT_LugIQvOyNDnMQwsMIgOgN-_aY,1100
|
|
85
|
-
shotgun/prompts/agents/state/system_state.j2,sha256=
|
|
86
|
+
shotgun/prompts/agents/state/system_state.j2,sha256=TQPnCLtmiNwQCbMxnCE7nLhXMJpKlBCnlNBKt7FTjuo,1033
|
|
86
87
|
shotgun/prompts/agents/state/codebase/codebase_graphs_available.j2,sha256=U-hy-H9bPwV0sYIHTZ5TESxc5EOCtntI8GUZOmJipJw,601
|
|
87
88
|
shotgun/prompts/codebase/__init__.py,sha256=NYuPMtmYM2ptuwf3YxVuotNlJOUq0hnjmwlzKcJkGK4,42
|
|
88
89
|
shotgun/prompts/codebase/cypher_query_patterns.j2,sha256=ufTx_xT3VoS76KcVUbIgGQx-bJoJHx3bBE3dagAXv18,8913
|
|
@@ -122,8 +123,8 @@ shotgun/utils/__init__.py,sha256=WinIEp9oL2iMrWaDkXz2QX4nYVPAm8C9aBSKTeEwLtE,198
|
|
|
122
123
|
shotgun/utils/env_utils.py,sha256=8QK5aw_f_V2AVTleQQlcL0RnD4sPJWXlDG46fsHu0d8,1057
|
|
123
124
|
shotgun/utils/file_system_utils.py,sha256=l-0p1bEHF34OU19MahnRFdClHufThfGAjQ431teAIp0,1004
|
|
124
125
|
shotgun/utils/update_checker.py,sha256=Xf-7w3Pos3etzCoT771gJe2HLkA8_V2GrqWy7ni9UqA,11373
|
|
125
|
-
shotgun_sh-0.1.0.
|
|
126
|
-
shotgun_sh-0.1.0.
|
|
127
|
-
shotgun_sh-0.1.0.
|
|
128
|
-
shotgun_sh-0.1.0.
|
|
129
|
-
shotgun_sh-0.1.0.
|
|
126
|
+
shotgun_sh-0.1.0.dev28.dist-info/METADATA,sha256=8jf2GyrCtSPnCcYTfwenqva0r6K3vVymDjGBWNCTLaY,11197
|
|
127
|
+
shotgun_sh-0.1.0.dev28.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
|
|
128
|
+
shotgun_sh-0.1.0.dev28.dist-info/entry_points.txt,sha256=asZxLU4QILneq0MWW10saVCZc4VWhZfb0wFZvERnzfA,45
|
|
129
|
+
shotgun_sh-0.1.0.dev28.dist-info/licenses/LICENSE,sha256=YebsZl590zCHrF_acCU5pmNt0pnAfD2DmAnevJPB1tY,1065
|
|
130
|
+
shotgun_sh-0.1.0.dev28.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|
|
File without changes
|