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:
    1. Best Agents (rovo:agent with 9 actions)
    2. Best app with Atlassian MCP (rovo:mcp with 6 strictly GET-only tools, including 0-LLM-call get-work-item-context for coding assistants)
    3. Best apps with Teamwork Graph integration (api.asUser().requestTeamworkGraph enriching impact-of-change with connected people and pull requests/deployments)
  • 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 via avi:jira:created/updated/commented:issue events 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 as aligned, drift, new_scope, or unclear and proposing updated spec wording ("Proposal — not applied").
  • Enforces "Evidence or silence" in code (src/core/drift.js): Every drift or new_scope finding must quote the requirement, the work item description, or a named comment word for word. parseDriftResult verifies each quote against its source in deterministic code and downgrades any finding it cannot prove to unclear.
  • Turns unpriced scope into a formal change request: One click on Flag as change request in the Jira issue panel adds the spectrail-change-request label 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, PR author, PR reviewer) and linked pull requests or deployments (marking PRs on completed items with needsReReview: true).
  • Works through three doors sharing one brain:
    1. Jira Issue Panel (jira:issuePanel) and Jira Admin Page (jira:adminPage) built with Forge UI Kit (@forge/react).
    2. Rovo Agent (rovo:agent) for natural-language spec tracing, impact analysis, and coverage checks in Rovo Chat.
    3. Forge MCP Server (rovo:mcp) so external coding agents like Claude Code can call get-work-item-context to read the requirement and stored drift findings before writing code—with zero new LLM calls.

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 zero permissions.external and 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, and src/demo.js wire workflows through dependency injection (createSpecTrail(deps)).
    • src/adapters/forge.js is the only file that touches Atlassian REST, KVS, Forge LLMs, or Teamwork Graph; src/adapters/shapes.js maps API responses and is tested against sanitised real recordings in test/recorded/.
  • Spec-driven & test-first engineering: Built across five feature increments (001 through 005) using GitHub Spec Kit (/speckit-specify → /speckit-plan → /speckit-tasks → /speckit-analyze → /speckit-implement) and strict RED-GREEN test-driven development (285 automated tests in node: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

  1. Best Agents (rovo:agent):
    • What it uses: rovo:agent module (key: spectrail-agent) backed by agent/prompt.txt, 4 conversation starters, and 9 actions (7 actionVerb: GET query/check actions + 2 admin-only actionVerb: UPDATE indexing actions).
    • What to look for in the app & video: In Rovo Chat, asking "Which work items drifted from the spec?" invokes list-flagged with verdict: "drift" and returns SPECDEMO-2 with its verified comment quote; asking "What breaks if we change FR-902?" invokes impact-of-change; asking "Which requirements have no work yet?" invokes spec-coverage and pinpoints FR-904 (80% coverage). Evaluated against a 15-question SPECDEMO benchmark in docs/06-evaluasi-rovo-dan-mcp.md.
  2. Best app with Atlassian MCP (rovo:mcp):
    • What it uses: rovo:mcp module (key: spectrail-mcp) exposing 6 strictly GET-only tools (get-requirement, get-work-item-context, check-work-item, impact-of-change, spec-coverage, list-flagged). Write and admin actions are excluded from rovo:mcp and enforced by automated manifest-consistency tests (test/handlers.test.js).
    • What to look for in the app & video: Claude Code connects to spectrail-mcp and calls get-work-item-context for SPECDEMO-2 before writing code—retrieving FR-902's exact spec wording, the drift verdict, and the verified "above 65 at loan maturity" comment quote in a single turn with 0 Forge LLM calls.
  3. Best apps with Teamwork Graph integration (requestTeamworkGraph):
    • What it uses: api.asUser().requestTeamworkGraph with 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 to 10 visible work items (done items prioritised first) into a single aliased curated GraphQL query (spectrail_workItemRelated) for jiraWorkItemLinkedExternalPullRequests and jiraWorkItemLinkedExternalDeployments.
    • 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-change attaches graph.people (deduplicated assignees, reporters, PR authors, and PR reviewers) and graph.related (pull requests and deployments, marking PRs on completed done items with needsReReview: true), protected by a hard 5,000 ms budget and a never-throw wrapper so Preview API unavailability never breaks impact analysis (docs/07-teamwork-graph.md).
  4. (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. In src/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, or comment:<id>), ensuring legitimate quotes pass while any paraphrased or invented quote is stripped and downgraded to unclear.
  • 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. In src/demo.js and src/core/demo.js, we designed a 6-step idempotent state machine (space → page → project → issues → comment → link) stored under the demo KVS 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. In src/core/results.js (redactForViewer) and src/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 200 even on ValidationError ("User is not permitted to query this organization"), RATE_LIMIT_EXCEEDED, or partial field failures. In src/core/graph.js (classifyGraphReply) and src/graph.js, we built a body-based classifier covering all 8 GraphStatus states (included, partial, no_graph_data, switched_off, not_needed, unavailable, rate_limited, timed_out) with a single conditional retry and a 5,000 ms timeout race so impact-of-change always succeeds.

Accomplishments that we're proud of

  • 100% deterministic evidence verification: Zero unverified drift or new_scope accusations can ever reach the UI, Rovo chat, or MCP client.
  • 285 passing automated tests (0 failures) 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 SPECDEMO evaluation 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 KiB single-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)

  1. Install on both Jira and Confluence:
  2. 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 project SPECDEMO (SPECDEMO-1..SPECDEMO-5), and links them.
  3. 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).
  4. 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-request label and post the evidence comment on SPECDEMO-3.
  5. Ask the SpecTrail Rovo Agent:
    • Open Rovo Chat, select SpecTrail, and ask:
      • "Which work items drifted from the spec?" → returns SPECDEMO-2 (FR-902).
      • "What breaks if we change FR-902?" → lists SPECDEMO-2 under affected work items plus the Teamwork Graph status sentence.
      • "Which requirements have no work yet?" → identifies FR-904 as uncovered (4 of 5 covered, 80%).
  6. Optional — Test MCP (get-work-item-context) & Teamwork Graph:
    • MCP: Connect Claude Code to the spectrail-mcp remote 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).
  7. 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.

Built With

Share this project:

Updates

Submission history