Packages

ptc_runner

0.12.0
0.13.0 0.12.0 0.11.0 0.10.1 0.10.0 0.9.0 0.8.0 0.7.0 0.6.0 0.5.2 0.5.1 0.5.0 0.4.1 0.4.0 0.3.4 0.3.3 0.3.2 0.3.1 0.3.0 0.2.0 0.1.0

Secure BEAM sandbox runtime for LLM code mode and MCP aggregation. Run concurrent LLM/tool clients safely while agents orchestrate approved tools, call upstream MCP/OpenAPI servers, and transform data.

HexDocs

Current section

Files

Jump to
Readme
21 Versions
6 Dependencies
Dependants
Files
Activity
ptc_runner docs guidelines epic-creation-guidelines.md
Raw

docs/guidelines/epic-creation-guidelines.md 

# Epic Creation Guidelines



An epic is a GitHub issue that serves as the source of truth for a feature. It links to specs, tracks progress via checkboxes, and coordinates related issues.



## Labels



| Label | Purpose |

|-------|---------|

| `type:epic` | Marks this issue as an epic |

| `status:active` | Current epic (only one at a time) |

| `epic:name` | Put on child issues (e.g., `epic:message-history`) |



## Structure



```markdown

# [Epic Name]



## Overview

Brief description of what this epic accomplishes.



## Specification Documents

- [Primary Spec](https://github.com/OWNER/REPO/blob/main/docs/specs/spec-name.md)



## Progress



### Phase 1: [Phase Name]

- [ ] Task description

- [ ] #123 - Existing issue (if already created)

- [x] #124 - Completed



### Phase 2: [Phase Name]

- [ ] Next phase tasks...



## Discovered Issues

- #130 - Found during implementation

```



## Guidelines



- **One active epic**: Remove `status:active` from old epic before adding to new

- **Full URLs**: Use `https://github.com/...` not relative paths (they don't work in issues)

- **Phases are sequential**: Complete Phase 1 before Phase 2

- **Just-in-time issues**: Don't create all issues upfront - create them as work progresses

- **Label child issues**: Add `epic:name` label to issues belonging to this epic

- **Deferred docs**: For phased refactorings with dual-write/backward-compat, defer doc updates to the final cleanup issue

- **Epic tracks progress, not specs**: Don't mark items as "✅ Complete" in spec documents - the epic checkboxes are the single source of truth for progress. Specs document requirements/architecture, not status.



## Task Sizing



Size each child task as a single right-sized issue. See [Issue Creation Guidelines — Sizing](issue-creation-guidelines.md#sizing) for the full criteria (testable value, ~100-500 lines, clear scope, and the too-large/too-small signals).



## References



- [GitHub Workflows](github-workflows.md) - How automation interacts with epics

- [Issue Creation Guidelines](issue-creation-guidelines.md) - Writing issues