Skip to content

Commit d366106

Browse files
shahzaibjshahzaibj
committed
Feature Orchestrator Plugin: Skills (2/5)
Add all specialized skills for the orchestration pipeline: - codebase-researcher: Systematic codebase exploration with SharePoint support - design-author: Design spec creation with multi-source (repo + SharePoint) - design-reviewer: Inline design review comment processing - feature-planner: PBI decomposition with mandatory file paths and API signatures - pbi-creator: ADO work item creation with dependency linking - pbi-dispatcher-github: Dispatch to Copilot coding agent on GitHub repos - pbi-dispatcher-ado: Dispatch via ADO Agency (future) - pbi-dispatcher-ado-swe: Dispatch via ADO Copilot SWE (tag + assign) - pr-validator: Validate agent PRs against PBI acceptance criteria - references/pbi-template.md: Standard PBI description template
1 parent 3d050b7 commit d366106

10 files changed

Lines changed: 1689 additions & 0 deletions

File tree

‎feature-orchestrator-plugin/skills/codebase-researcher/SKILL.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
name: codebase-researcher
3+
description: Systematically explore codebases to find implementations, patterns, and architecture. Use for "where is X implemented", "how does Y work", "trace the flow of", or any request requiring codebase exploration with evidence-based findings.
4+
---
5+
6+
# Codebase Researcher
7+
8+
Explore this codebase systematically with evidence-based findings.
9+
10+
## Project Knowledge
11+
12+
Read `.github/copilot-instructions.md` for project-wide conventions and coding standards.
13+
14+
## Repository Structure
15+
16+
Discover the repository structure by exploring the workspace — check for modules,
17+
sub-directories with their own build files, and README files.
18+
19+
| Module | Purpose | Key Paths |
20+
|--------|---------|-----------|
21+
| *Discover by exploring the workspace* | | |
22+
23+
**⚠️ CRITICAL: Always search across ALL modules/directories.** Code is often shared or duplicated.
24+
25+
## Core Principles
26+
27+
1. **Never guess** — Only report what is actually found in the repo
28+
2. **Always cite sources** — Every finding must include file path and line numbers
29+
3. **Acknowledge gaps** — Explicitly state when something cannot be found
30+
4. **Rate confidence** — Assign HIGH/MEDIUM/LOW to each finding
31+
5. **Search all modules** — Check every relevant directory for each query
32+
33+
## Research Workflow
34+
35+
### Step 1: Understand the Target
36+
37+
Clarify what to find:
38+
- Feature/concept name
39+
- Which layer (client, service, shared, etc.)
40+
- Expected patterns (class names, function signatures)
41+
42+
### Step 2: Search Strategy
43+
44+
Execute searches in this order, **always searching across all modules**:
45+
46+
1. **Semantic search** — Start with natural language query
47+
2. **Grep search** — Exact patterns, class names, error codes
48+
3. **File search** — Find by naming convention (e.g., `**/*Operation*.kt`)
49+
4. **Directory exploration** — List relevant directories in each module
50+
5. **Read files** — Confirm findings with actual code
51+
52+
### Step 3: Trace Call Chains
53+
54+
For the feature area being researched, trace the complete flow:
55+
- Identify the entry point
56+
- Follow across module boundaries
57+
- Note threading model and error handling at each boundary
58+
59+
### Step 4: Identify Invariants
60+
61+
Search for constraints that govern the affected code:
62+
- Threading annotations, synchronization
63+
- Serialization contracts, protocol versions
64+
- Lifecycle dependencies, feature flags
65+
66+
### Step 5: Validate Findings
67+
68+
For each potential finding:
69+
- Read the actual code (don't rely only on search snippets)
70+
- Identify which module it belongs to
71+
- Note the exact location (file + line range)
72+
- Assess confidence level
73+
74+
### Step 6: Report Results
75+
76+
```markdown
77+
## Research: [Topic]
78+
79+
### Findings
80+
81+
#### Finding 1: [Brief description]
82+
- **Module**: [which module]
83+
- **File**: [path/to/file.ext](path/to/file.ext#L10-L25)
84+
- **Confidence**: HIGH | MEDIUM | LOW
85+
- **Evidence**: [What makes this the right code]
86+
87+
[Code snippet if helpful]
88+
89+
#### Finding 2: ...
90+
91+
### Unknowns & Risk Areas
92+
93+
- [Thing searched for but not found]
94+
- Search attempts: [what was tried]
95+
- [Areas that might be affected but couldn't confirm]
96+
97+
### Suggested Next Steps
98+
99+
- [Additional areas to explore]
100+
- [Related code that might be relevant]
101+
```
102+
103+
## Confidence Levels
104+
105+
| Level | Criteria |
106+
|-------|----------|
107+
| **HIGH** | Exact match. Code clearly implements the feature. Names match. |
108+
| **MEDIUM** | Likely match. Code appears related but naming differs or implementation is partial. |
109+
| **LOW** | Possible match. Found tangentially related code, or inference required. |
110+
111+
## Data Flow Investigation
112+
113+
When asked about **what data is returned**, **how data flows**, or **what happens to data**:
114+
115+
1. **Find the Data Structure** — Confirm the field exists, check serialization
116+
2. **Find Construction/Population Code** — Search for Builder/factory methods
117+
3. **Check Conditional Logic** — Search for `if` statements, feature flag checks, version checks
118+
4. **Trace the Complete Flow** — Follow from entry → processing → response → return
119+
120+
### Flow Investigation Pitfalls
121+
122+
❌ Don't stop after finding a field definition — check actual behavior
123+
❌ Don't assume data flows unchanged — check for filtering/transformation
124+
❌ Don't ignore version/flag checks — behavior often changes based on these
125+
✅ Search for Builder usage and construction patterns
126+
✅ Look for Adapter/Converter classes in the flow
127+
✅ Check for conditional logic based on configuration or feature flags
128+
129+
## Anti-Patterns to Avoid
130+
131+
| Anti-Pattern | Problem | Correct Approach |
132+
|--------------|---------|------------------|
133+
| Searching only one module | Miss cross-module code | Search ALL modules |
134+
| "This is likely in..." | Speculation without evidence | Search first, report only found |
135+
| Path without line numbers | Imprecise, hard to verify | Always include line numbers |
136+
| Stopping at definition | Misses conditional logic | Trace to construction/adapter |
137+
| Brief summary | Loses detail for next step | Be thorough and comprehensive |

‎feature-orchestrator-plugin/skills/design-author/SKILL.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
name: design-author
3+
description: Create detailed design specs for features. Use when asked to design a feature, create a design spec, write a design doc, or create an implementation plan. Triggers include "design this feature", "create a design spec", "write a design doc".
4+
---
5+
6+
# Design Author
7+
8+
Create detailed design specs for features, save them locally, and optionally open PRs for review.
9+
10+
## Configuration
11+
12+
Read `.github/orchestrator-config.json` for:
13+
- `design.docsPath` — where to save design docs (e.g., `design-docs/` or `docs/designs/`)
14+
- `design.templatePath` — path to design spec template (optional)
15+
- `design.folderPattern` — folder naming pattern (e.g., `[{platform}] {featureName}`)
16+
- `design.reviewRepo` — repo for design review PRs (optional)
17+
18+
If no config, save to `docs/designs/` and use the built-in template below.
19+
20+
## Design Spec Template
21+
22+
Key sections every design spec should include:
23+
24+
1. **Title** — Feature name
25+
2. **Components** — Which modules/repos affected
26+
3. **Problem description** — User problem, business context, examples
27+
4. **Requirements** — Functional requirements (must-have)
28+
5. **System Qualities** — Performance, telemetry, security, supportability
29+
6. **Solution options** — At least 2 options with pseudo code, pros/cons
30+
7. **Solution Decision** — Recommended option with reasoning
31+
8. **API surface** — Public/internal classes, methods (if applicable)
32+
9. **Data flow** — Request/response flow across components
33+
10. **Feature flag** — Flag name and gating strategy (if applicable)
34+
11. **Telemetry** — Key metrics, span names, success/failure signals
35+
12. **Testing strategy** — Unit tests, integration tests, E2E coverage
36+
13. **Rollout plan** — Staged rollout, feature flag configuration
37+
14. **Cross-repo impact** — Which repos need changes and in what order
38+
39+
If a template file exists at the configured `design.templatePath`, follow that instead.
40+
41+
## Workflow
42+
43+
### Step 1: Understand the Feature
44+
45+
Gather from the developer:
46+
1. What the feature does and why it's needed
47+
2. Which components/flows it affects
48+
3. Scope boundaries (in/out)
49+
4. Any existing designs to reference
50+
51+
### Step 2: Research the Codebase
52+
53+
Use the `codebase-researcher` skill to:
54+
- Understand how related functionality currently works
55+
- Identify which repos/files would be affected
56+
- Find existing patterns to follow (feature flags, error handling, telemetry)
57+
- Check for existing design docs on the same topic
58+
59+
### Step 3: Research Existing Designs
60+
61+
If `design.docsPath` is configured, search for related designs:
62+
```bash
63+
ls <docsPath>/ | grep -i "<keyword>"
64+
```
65+
Use existing designs as **style reference and historical context**, not ground truth for behavior.
66+
67+
### Step 4: Write the Design Spec
68+
69+
Create the spec at:
70+
```
71+
<docsPath>/<folderPattern>/<spec-name>.md
72+
```
73+
74+
For the **Solution options** section:
75+
- Always provide at least 2 options
76+
- Include pseudo code / API signatures for each
77+
- List concrete pros/cons
78+
- Clear recommendation in Solution Decision
79+
80+
### Agent Implementation Notes
81+
82+
Write the design knowing a coding agent will implement it. Be explicit about:
83+
- Class boundaries and responsibilities
84+
- Threading model
85+
- Error contracts
86+
- Integration points with other modules
87+
88+
### Step 5: Present Design for Review
89+
90+
After writing, **STOP and present choices** using `askQuestion`:
91+
92+
```
93+
askQuestion({
94+
question: "Design spec written. What would you like to do?",
95+
options: [
96+
{ label: "📖 Review locally", description: "Open in editor for inline review" },
97+
{ label: "✅ Approve & plan PBIs", description: "Skip PR, move to work item planning" },
98+
{ label: "📋 Open draft PR", description: "Push to review repo as draft PR" },
99+
{ label: "🚀 Open published PR", description: "Push and publish PR for team review" },
100+
{ label: "✏️ Request changes", description: "Tell me what to revise" }
101+
]
102+
})
103+
```
104+
105+
**MANDATORY**: Wait for the developer's explicit choice. Do NOT auto-select.
106+
107+
### Step 5a: Local Review (option 1)
108+
109+
Open the file: `code "<spec path>"`
110+
111+
Tell the developer:
112+
> "The spec is open. Here's how to review:
113+
> 1. Click the **+ icon** in the gutter to add inline comments
114+
> 2. When done, click the status bar button to submit comments
115+
> 3. I'll address each comment and present choices again"
116+
117+
### Step 5b: Push and Create PR (options 3 or 4)
118+
119+
**Branch naming**: Discover alias from `git config user.email` (strip @domain):
120+
```powershell
121+
$alias = (git config user.email) -replace '@.*', ''
122+
git checkout -b "$alias/design-<feature-name-kebab-case>"
123+
```
124+
125+
**Git workflow** (from design docs directory):
126+
```powershell
127+
cd <docsPath>/
128+
git add "<folder name>"
129+
git commit -m "Add design spec: <Feature Name>"
130+
git push origin $BRANCH_NAME
131+
```
132+
133+
**Create PR**: Use `gh pr create` or ADO MCP tools if available.
134+
- Set `--draft` for option 3, omit for option 4
135+
- **PR description**: Use actual line breaks or HTML formatting, NOT literal `\n` escape sequences
136+
- Target branch: `main` (or the repo's default branch)
137+
138+
Present the PR link:
139+
```markdown
140+
### PR Created
141+
**PR**: [link to PR]
142+
**Status**: Draft / Published
143+
144+
### How to Review
145+
1. Open the PR link above
146+
2. Use inline commenting to leave feedback
147+
3. When done, say: **"address my design review comments"**
148+
4. I'll read the comments and update the spec
149+
150+
When the team approves, say: **"design approved, plan the PBIs"**
151+
```
152+
153+
### Step 6: Address Review Comments
154+
155+
When asked to address comments (from PR or local review):
156+
1. Read the feedback (from PR comments or `reviews.json`)
157+
2. For each comment:
158+
- Understand the feedback
159+
- Edit the local design spec to address it
160+
- If on a PR branch, reply to the thread confirming the resolution
161+
3. Commit and push the updates to the same branch
162+
4. Report a summary of changes made
163+
5. Return to Step 5 (present choices again)
164+
165+
### Step 7: Proceed to Implementation
166+
167+
When the developer confirms the design is approved:
168+
1. The PR can be completed/merged
169+
2. Hand off to the `feature-planner` skill for PBI decomposition
170+
171+
## Important Caveats
172+
173+
- **Existing designs may be outdated** — last-minute PR discussions often cause code to deviate.
174+
Always verify proposed patterns against the **current codebase**, not just existing designs.
175+
- **Use existing designs as style reference**, not as ground truth for current behavior.
176+
- For paths with brackets `[]` or spaces, use PowerShell with `-LiteralPath`
177+
178+
### Open Questions
179+
180+
If there are genuine unknowns during design, use `askQuestion` to resolve them interactively,
181+
or list them in the spec for the team to discuss during review.

0 commit comments

Comments
 (0)