📋 Pre-flight Checks
🔍 Problem Description
The orchestrator has two hardcoded proactive behaviors — SDD and Engram — both with explicit self-checks that make them work reliably. But projects can define their own proactive instructions (via auto-invoke tables, narrative rules like "before X do Y", or skill frontmatter with auto_invoke metadata), and the orchestrator silently ignores all of them.
Why I think it happens: from what I can tell, the orchestrator reads project instructions but seems to treat them as passive context. As far as I can see, it doesn't have a mechanism to parse them for proactive behaviors, classify which ones are its own responsibility, or act on them without user reminders.
Concrete example: Imagine a project that defines two custom skills in its CLAUDE.md auto-invoke table:
- A session documentation skill that should create and update a session file whenever significant work is completed or a technical decision is made.
- A changelog skill that should add entries to
CHANGELOG.md coordinated with the session documentation.
Both would be cross-cutting session concerns — I don't think any implementation sub-agent has the session-wide visibility to handle them. In my experience, the orchestrator completes substantial work (files created, decisions made) and never triggers either skill. I end up having to manually ask at the end of the session.
I believe the same gap would apply to any project-defined orchestrator-level workflow: compliance gates before PRs, spec verification before implementation, PRD generation before SDD, deployment tracking, audit trails, etc.
Sub-agent-level proactivity already works — sub-agents discover and load relevant skills via SKILL LOADING. The orchestrator has no equivalent for its own responsibilities.
💡 Proposed Solution
I'd like to propose a project context bootstrap that runs once per session and gives the orchestrator the ability to discover and act on project-defined proactive instructions. At a high level:
- Discover proactive instructions from project sources (auto-invoke tables, narrative workflow rules, skill
auto_invoke metadata).
- Classify each as orchestrator-level (session lifecycle, cross-cutting gates) or sub-agent-level (implementation patterns — already handled).
- Act via a self-check loop similar to Engram's: after each task, evaluate if any orchestrator-level trigger fired. Also support pre-action gates (e.g., "verify X before delegating implementation").
- Persist the result in Engram so it survives compactions and future sessions skip re-analysis.
Classification should be backward compatible — no changes required to existing skills. A level field in skill frontmatter would take priority when present; otherwise the orchestrator infers from trigger nature.
I have a detailed PRD with design examples and would include it in the PR if this direction is accepted.
I'm already exploring the implementation on my end. Happy to adapt based on feedback from maintainers.
📦 Affected Area
Skills (SDD phases, orchestrator)
🔄 Alternatives Considered
- Hardcode each workflow into the orchestrator: How SDD and Engram work today, but doesn't scale to arbitrary project-defined workflows.
- Rely on sub-agents: They lack session-wide visibility. Cross-cutting concerns get silently dropped because no sub-agent owns them.
- Bloat the orchestrator prompt with reminders: Wastes the most expensive context (orchestrator survives the full conversation) and still doesn't generalize.
📎 Additional Context
Related to #5 (sub-agents spawning without project context), resolved in v2.3.0. That fix addressed the sub-agent level; this proposal targets what I think is the same gap at the orchestrator level.
This is my first time contributing to an open-source project on GitHub, so I apologize in advance if I'm not following conventions perfectly. I'm happy to adjust anything — just let me know.
📋 Pre-flight Checks
status:approvedbefore a PR can be opened🔍 Problem Description
The orchestrator has two hardcoded proactive behaviors — SDD and Engram — both with explicit self-checks that make them work reliably. But projects can define their own proactive instructions (via auto-invoke tables, narrative rules like "before X do Y", or skill frontmatter with
auto_invokemetadata), and the orchestrator silently ignores all of them.Why I think it happens: from what I can tell, the orchestrator reads project instructions but seems to treat them as passive context. As far as I can see, it doesn't have a mechanism to parse them for proactive behaviors, classify which ones are its own responsibility, or act on them without user reminders.
Concrete example: Imagine a project that defines two custom skills in its
CLAUDE.mdauto-invoke table:CHANGELOG.mdcoordinated with the session documentation.Both would be cross-cutting session concerns — I don't think any implementation sub-agent has the session-wide visibility to handle them. In my experience, the orchestrator completes substantial work (files created, decisions made) and never triggers either skill. I end up having to manually ask at the end of the session.
I believe the same gap would apply to any project-defined orchestrator-level workflow: compliance gates before PRs, spec verification before implementation, PRD generation before SDD, deployment tracking, audit trails, etc.
Sub-agent-level proactivity already works — sub-agents discover and load relevant skills via SKILL LOADING. The orchestrator has no equivalent for its own responsibilities.
💡 Proposed Solution
I'd like to propose a project context bootstrap that runs once per session and gives the orchestrator the ability to discover and act on project-defined proactive instructions. At a high level:
auto_invokemetadata).Classification should be backward compatible — no changes required to existing skills. A
levelfield in skill frontmatter would take priority when present; otherwise the orchestrator infers from trigger nature.I have a detailed PRD with design examples and would include it in the PR if this direction is accepted.
I'm already exploring the implementation on my end. Happy to adapt based on feedback from maintainers.
📦 Affected Area
Skills (SDD phases, orchestrator)
🔄 Alternatives Considered
📎 Additional Context
Related to #5 (sub-agents spawning without project context), resolved in v2.3.0. That fix addressed the sub-agent level; this proposal targets what I think is the same gap at the orchestrator level.
This is my first time contributing to an open-source project on GitHub, so I apologize in advance if I'm not following conventions perfectly. I'm happy to adjust anything — just let me know.