Devpost Submission — SpecTrail (Atlassian Codegeist 2026)
Copy-ready English submission text for Devpost. All claims and metrics below match the verified codebase, automated test suite, and live deployment on spectrail.atlassian.net.
- Category:
Apps for Software Teams - Bonus prizes claimed:
- Best Agents (
rovo:agentwith 9 actions) - Best app with Atlassian MCP (
rovo:mcpwith 6 strictlyGET-only tools, including 0-LLM-callget-work-item-contextfor coding assistants) - Best apps with Teamwork Graph integration (
api.asUser().requestTeamworkGraphenrichingimpact-of-changewith connected people and pull requests/deployments)
- Best Agents (
- App ID:
ari:cloud:ecosystem::app/b280670e-7b75-418a-86e9-69e418d74bcb
Elevator pitch (one line)
SpecTrail keeps the thread from requirement to delivery: it catches Jira work that has drifted from your Confluence spec, or quietly added scope, and proves every claim with verbatim quotes verified in code.
Inspiration
I am a system analyst at an IT vendor. We write functional specifications in Confluence for enterprise clients, then deliver from Jira. Within two sprints the two silently disagree: a client decision lands in a Jira comment ("upper age limit is now 65 for civil servants") and never reaches the Confluence spec ("age below 21 or above 60"); a story quietly grows an unpriced feature ("also send a WhatsApp notification on approval"); and when a requirement changes mid-project, nobody knows which completed stories need re-testing or which pull requests need re-review. QA tests against the spec, developers build against the ticket, and the team absorbs the rework and scope creep.
What it does
- Indexes Confluence specifications (
index-spec-page): Extracts requirement IDs (FR-901,FR-902,NFR-901, ...) and their full wording from Confluence pages, whether written in tables or plain paragraphs. - Links Jira work items automatically (
refresh-links+ issue trigger): Maps every Jira work item that mentions a requirement ID in its summary, description, acceptance criteria, or comments, keeping the index current viaavi:jira:created/updated/commented:issueevents without calling the AI model. - Detects drift and unpriced scope (
check-work-item): Uses Claude via Forge LLMs (@forge/llm) to compare a work item and its comments against each linked requirement, classifying the pair asaligned,drift,new_scope, orunclearand proposing updated spec wording ("Proposal — not applied"). - Enforces "Evidence or silence" in code (
src/core/drift.js): Everydriftornew_scopefinding must quote the requirement, the work item description, or a named comment word for word.parseDriftResultverifies each quote against its source in deterministic code and downgrades any finding it cannot prove tounclear. - Turns unpriced scope into a formal change request: One click on Flag as change request in the Jira issue panel adds the
spectrail-change-requestlabel and posts a formatted evidence comment to the Jira work item (asUser), making scope creep visible for pricing and sign-off. - Answers blast-radius and coverage questions (
impact-of-change,spec-coverage): Shows open work affected, Done work that needs re-testing (reopenRisk), uncovered requirements with zero Jira tickets, and—when Teamwork Graph enrichment is enabled—the connected people (assignee,reporter, PRauthor, PRreviewer) and linked pull requests or deployments (marking PRs on completed items withneedsReReview: true). - Works through three doors sharing one brain:
- Jira Issue Panel (
jira:issuePanel) and Jira Admin Page (jira:adminPage) built with Forge UI Kit (@forge/react). - Rovo Agent (
rovo:agent) for natural-language spec tracing, impact analysis, and coverage checks in Rovo Chat. - Forge MCP Server (
rovo:mcp) so external coding agents like Claude Code can callget-work-item-contextto read the requirement and stored drift findings before writing code—with zero new LLM calls.
- Jira Issue Panel (
How we built it
- 100% Forge-native, Runs on Atlassian: Built on the Node.js 22 runtime (
nodejs22.x) using@forge/api,@forge/kvs,@forge/llm,@forge/react,@forge/bridge, and@forge/resolver. SpecTrail declares zeropermissions.externaland uses no external servers. - Hexagonal / deterministic core architecture:
src/core/*holds pure, zero-I/O modules for spec parsing (requirements.js), linking (links.js), prompt construction and quote verification (drift.js), check planning, freshness status and viewer permission redaction (results.js), impact (impact.js), Teamwork Graph query building, reply classification and parsing (graph.js), 20-item list truncation (truncate.js), settings validation (config.js), KVS budget guards (budget.js), ADF comment generation (adf.js), and judge demo state (demo.js).src/service.js,src/queries.js,src/graph.js,src/settings.js, andsrc/demo.jswire workflows through dependency injection (createSpecTrail(deps)).src/adapters/forge.jsis the only file that touches Atlassian REST, KVS, Forge LLMs, or Teamwork Graph;src/adapters/shapes.jsmaps API responses and is tested against sanitised real recordings intest/recorded/.
- Spec-driven & test-first engineering: Built across five feature increments (
001through005) using GitHub Spec Kit (/speckit-specify→/speckit-plan→/speckit-tasks→/speckit-analyze→/speckit-implement) and strict RED-GREEN test-driven development (285automated tests innode:test).
How it meets the technology requirement
SpecTrail is built natively on Atlassian Forge across Jira Cloud, Confluence Cloud, Rovo, Forge LLMs, Forge MCP, and Teamwork Graph, combining eight Forge module types in manifest.yml: jira:issuePanel (UI Kit panel on every Jira issue), jira:adminPage (UI Kit onboarding, indexing, and settings console), trigger (avi:jira:created:issue, avi:jira:updated:issue, avi:jira:commented:issue), llm (Atlassian-hosted Claude via @forge/llm, defaulting to claude-sonnet-5), rovo:agent (spectrail-agent), rovo:mcp (spectrail-mcp), action (9 actions), and function (12 handlers), backed by Forge KVS (storage:app). Every user-facing read and write executes as the calling user (api.asUser()) with fail-closed Confluence permission redaction (redactForViewer), and the app declares zero external egress (Runs on Atlassian).
Bonus prizes claimed & what to look for
- Best Agents (
rovo:agent):- What it uses:
rovo:agentmodule (key: spectrail-agent) backed byagent/prompt.txt,4conversation starters, and9actions (7actionVerb: GETquery/check actions +2admin-onlyactionVerb: UPDATEindexing actions). - What to look for in the app & video: In Rovo Chat, asking "Which work items drifted from the spec?" invokes
list-flaggedwithverdict: "drift"and returnsSPECDEMO-2with its verified comment quote; asking "What breaks if we change FR-902?" invokesimpact-of-change; asking "Which requirements have no work yet?" invokesspec-coverageand pinpointsFR-904(80%coverage). Evaluated against a 15-questionSPECDEMObenchmark indocs/06-evaluasi-rovo-dan-mcp.md.
- What it uses:
- Best app with Atlassian MCP (
rovo:mcp):- What it uses:
rovo:mcpmodule (key: spectrail-mcp) exposing6strictlyGET-only tools (get-requirement,get-work-item-context,check-work-item,impact-of-change,spec-coverage,list-flagged). Write and admin actions are excluded fromrovo:mcpand enforced by automated manifest-consistency tests (test/handlers.test.js). - What to look for in the app & video: Claude Code connects to
spectrail-mcpand callsget-work-item-contextforSPECDEMO-2before writing code—retrievingFR-902's exact spec wording, thedriftverdict, and the verified"above 65 at loan maturity"comment quote in a single turn with 0 Forge LLM calls.
- What it uses:
- Best apps with Teamwork Graph integration (
requestTeamworkGraph):- What it uses:
api.asUser().requestTeamworkGraphwith four narrow per-object read scopes (read:graph:issue:jira,read:graph:pull-request:external,read:graph:deployment:external,read:graph:user:atlassian), batching up to10visible work items (doneitems prioritised first) into a single aliased curated GraphQL query (spectrail_workItemRelated) forjiraWorkItemLinkedExternalPullRequestsandjiraWorkItemLinkedExternalDeployments. - What to look for in the app & video: On the Jira admin page, the Check Teamwork Graph button runs
spectrail_echoCheck(checkGraph) to verify graph reachability. When enabled (graphEnrichment: true),impact-of-changeattachesgraph.people(deduplicated assignees, reporters, PR authors, and PR reviewers) andgraph.related(pull requests and deployments, marking PRs on completeddoneitems withneedsReReview: true), protected by a hard5,000 msbudget and a never-throw wrapper so Preview API unavailability never breaks impact analysis (docs/07-teamwork-graph.md).
- What it uses:
- (Optional 4th Bonus — Best Marketplace published app: Claimed on the Devpost form only if a Marketplace listing ticket is submitted prior to the deadline; otherwise omitted so every claimed bonus is 100% substantiated.)
Challenges we ran into
- Preventing hallucinated quotes across Unicode punctuation: LLMs frequently normalise curly apostrophes (
’→'), en/em-dashes (–/—→-), or line breaks when quoting text. Insrc/core/drift.js(normaliseForMatch), we built a deterministic normaliser that folds only whitespace, quote styles, and dash variants while requiring an exact substring match against the named source (requirement,description,acceptance, orcomment:<id>), ensuring legitimate quotes pass while any paraphrased or invented quote is stripped and downgraded tounclear. - Respecting Forge's 25-second UI resolver limit during one-click judge onboarding: Creating a Confluence page, a Jira project (
SPECDEMO), five work items, a comment, and indexing/linking them in a single resolver call risks hitting the platform timeout. Insrc/demo.jsandsrc/core/demo.js, we designed a 6-step idempotent state machine (space→page→project→issues→comment→link) stored under thedemoKVS key so each step executes in its own quick call and can resume cleanly if interrupted. - Cross-product permission redaction (
fail-closed): A Jira user who can view a work item might not have permission to read the linked Confluence spec page. Insrc/core/results.js(redactForViewer) andsrc/queries.js, if the caller cannot view the Confluence page, SpecTrail redacts the requirement text, page title/URL, suggested spec wording, AI summary, and any spec-sourced quotes across the issue panel, Rovo actions, and MCP tools—showing only the verdict and quotes taken from the Jira work item itself. - Teamwork Graph Preview resilience & HTTP 200 GraphQL errors: Teamwork Graph returns HTTP
200even onValidationError("User is not permitted to query this organization"),RATE_LIMIT_EXCEEDED, or partial field failures. Insrc/core/graph.js(classifyGraphReply) andsrc/graph.js, we built a body-based classifier covering all 8GraphStatusstates (included,partial,no_graph_data,switched_off,not_needed,unavailable,rate_limited,timed_out) with a single conditional retry and a5,000 mstimeout race soimpact-of-changealways succeeds.
Accomplishments that we're proud of
- 100% deterministic evidence verification: Zero unverified
driftornew_scopeaccusations can ever reach the UI, Rovo chat, or MCP client. - 285 passing automated tests (
0failures) across 20 test suites (npm test), including recorded real Jira, Confluence, and Teamwork Graph payload tests (test/recorded/), manifest-consistency assertions, and cross-artifact submission checks (test/submission.test.js), all runnable offline in ~1.5 seconds. - Under-3-minute judge onboarding with zero residue: Any judge can install via the link, click Create demo project, experience the full Confluence-to-Jira-to-Rovo-to-MCP loop on realistic loan-origination data (
SPECDEMO), and click Remove demo data to delete the project, Confluence page (including trash), and KVS records completely. - Zero-LLM-call context for coding assistants (
get-work-item-context): Developers using Claude Code or Cursor get instant requirement wording and verified drift warnings before writing a single line of code, without spending a cent on AI tokens. - 15-question
SPECDEMOevaluation benchmark (docs/06-evaluasi-rovo-dan-mcp.md): Every Rovo action and MCP tool is benchmarked across drift filtering, scope-creep detection, open/done impact analysis, coverage gaps, loose ID normalisation ("fr 902"→"FR-902"), and write-boundary refusals.
What's next for SpecTrail
- Confluence inline comment proposals: Let spec owners turn a "Proposal — not applied" wording suggestion into a Confluence inline comment on the exact requirement row with one click for stakeholder approval.
- Bitbucket & GitHub PR checks: Automatically annotate pull requests that reference a Jira work item when the linked requirement has drifted or changed after the branch was created.
- Per-requirement KVS keys / Forge SQL storage: Scale beyond the
230 KiBsingle-key KVS guard to support enterprise monorepo specifications with thousands of requirements. - Atlassian Marketplace listing: Publish SpecTrail on the Atlassian Marketplace for general availability.
How to test (for judges)
- Install on both Jira and Confluence:
- Open the SpecTrail distribution/installation link (
ari:cloud:ecosystem::app/b280670e-7b75-418a-86e9-69e418d74bcb, pre-selected for both Confluence and Jira): https://developer.atlassian.com/console/install/b280670e-7b75-418a-86e9-69e418d74bcb?signature=AYABeAcbd2sCEDPzYhA3tUJlN9IAAAADAAdhd3Mta21zAEthcm46YXdzOmttczp1cy13ZXN0LTI6NzA5NTg3ODM1MjQzOmtleS83MDVlZDY3MC1mNTdjLTQxYjUtOWY5Yi1lM2YyZGNjMTQ2ZTcAuAECAQB4CxqLTo9l4lqXuFjNim1xJM%2Bp%2F3TVP9xHS2BrU5DRRucBFX86iUC7xrSrHpZxjxFcwAAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDA7NF38nUecAFhuPTgIBEIA7nYWoShu%2Bn9JkLoZTkeiy%2FzB%2FqQZ62XT4AVKhckqZNzuQwxsyUwCgNHG%2FHpHF2Mvsn%2F2ROEmjIRnxuHEAB2F3cy1rbXMAS2Fybjphd3M6a21zOmV1LXdlc3QtMTo3MDk1ODc4MzUyNDM6a2V5LzQ2MzBjZTZiLTAwYzMtNGRlMi04NzdiLTYyN2UyMDYwZTVjYwC4AQICAHi9bVMAkme4qVQX1fQHo6ePw3H40A7cGfz7yrmSfBWMXgFVVHcIxPpQLw92BjCRxn5IAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMJL%2Bbu%2FH9%2FP8TqT2uAgEQgDsLXaVuiEtJK9ySvlccKtD0GoEpZcwejap7Dn2Ggst4xVymJK0M61BYpMbUNRkwuG4RNdt%2FEFsjKw1BwgAHYXdzLWttcwBLYXJuOmF3czprbXM6dXMtZWFzdC0xOjcwOTU4NzgzNTI0MzprZXkvNmMxMjBiYTAtNGNkNS00OTg1LWI4MmUtNDBhMDQ5NTJjYzU3ALgBAgIAeDYASx0XCjkny4iLV6vz%2BKtEGSGT6kdt0QRpkn6D%2FlVEAb7nWwg52uJltNAtTGCHb7YAAAB%2BMHwGCSqGSIb3DQEHBqBvMG0CAQAwaAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAx87%2BdrctIpWIOeykUCARCAO1W3fANHCohDMeKERY%2BXovVt3brRDOPl3o1m6R%2FewQ3cnYKUU3NKgtoEbH5h44mor3IFhZdmwQ9%2BDUq6AgAAAAAMAAAQAAAAAAAAAAAAAAAAAL0OtZykqKzYpWrNhoNovWz%2F%2F%2F%2F%2FAAAAAQAAAAAAAAAAAAAAAQAAADL%2FTLwOfWVF1PSuZoJNzoo2Z6Ue5x%2F0udmujCATYudj4tfW3a3P0HOOzjZK6PmaH7Gdm%2Bk9S0zrwUooeZrjvCmDixw%3D&product=confluence&product=jira - Select your evaluation site and install onto both Jira and Confluence.
- Open the SpecTrail distribution/installation link (
- Create the one-click demo project (
SPECDEMO):- In Jira, navigate to Jira Settings (⚙️) → Apps → SpecTrail and click Create demo project.
- Wait ~15–20 seconds while SpecTrail creates the Confluence spec page (
FR-901..FR-904,NFR-901) in your personal space and the Jira projectSPECDEMO(SPECDEMO-1..SPECDEMO-5), and links them.
- See a verified drift finding (
SPECDEMO-2/FR-902):- Open
SPECDEMO-2(Age validation for FR-902) and click Check against spec in the SpecTrail panel. - Confirm the Drifted from spec verdict, the verbatim spec quote (
"below 21 or above 60 at loan maturity"), the verbatim client comment quote ("above 65 at loan maturity"), and the proposed spec update (Proposal — not applied).
- Open
- See new scope & flag a change request (
SPECDEMO-3/FR-903):- Open
SPECDEMO-3(Approve or reject (FR-903)) and click Check against spec. - Confirm the New scope verdict quoting the WhatsApp notification requirement, then click Flag as change request to apply the
spectrail-change-requestlabel and post the evidence comment onSPECDEMO-3.
- Open
- Ask the SpecTrail Rovo Agent:
- Open Rovo Chat, select SpecTrail, and ask:
"Which work items drifted from the spec?"→ returnsSPECDEMO-2(FR-902)."What breaks if we change FR-902?"→ listsSPECDEMO-2under affected work items plus the Teamwork Graph status sentence."Which requirements have no work yet?"→ identifiesFR-904as uncovered (4of5covered,80%).
- Open Rovo Chat, select SpecTrail, and ask:
- Optional — Test MCP (
get-work-item-context) & Teamwork Graph:- MCP: Connect Claude Code to the
spectrail-mcpremote MCP endpoint (docs/06-evaluasi-rovo-dan-mcp.md§3) and ask"Before I start coding SPECDEMO-2, get its SpecTrail requirement and drift context"(0 LLM calls). - Teamwork Graph: On Jira Settings → Apps → SpecTrail, click Check Teamwork Graph (
checkGraph) and toggle Include Teamwork Graph context in impact analysis on (docs/07-teamwork-graph.md).
- MCP: Connect Claude Code to the
- Clean up with one click:
- Return to Jira Settings → Apps → SpecTrail and click Remove demo data to delete project
SPECDEMO, the demo Confluence page, and all stored demo records.
- Return to Jira Settings → Apps → SpecTrail and click Remove demo data to delete project
Built With
- atlassian-forge
- claude
- confluence
- forge-kvs
- forge-llm
- forge-ui-kit
- graphql
- javascript
- jira
- mcp
- node.js
- react
- rest-api
- rovo
- teamwork-graph