The emergence of AI-powered coding assistants has reshaped how developers approach software creation, yet integrating these agents into established enterprise workflows remains a challenge. sddflow, now available on PyPI, bridges this gap by offering a command-line interface built around Spec-Driven Development (SDD) principles. It treats detailed specifications as first-class artifacts, enabling AI agents to consume, act upon, and update them in a structured manner. This approach aligns well with the growing demand for traceability and compliance in AI-generated code, especially in regulated industries. By anchoring agent behavior to explicit specs, teams can reduce ambiguity, improve review efficiency, and maintain a clear audit trail from requirement to release. The tool’s release on PyPI signals a maturing ecosystem where developer experience and process rigor converge.
At its core, sddflow orchestrates the software development lifecycle through tight integration with Atlassian’s Jira and Confluence platforms. Users define features, tasks, and acceptance criteria in YAML-based specification files stored under a .specify directory. The CLI then synchronizes these artifacts with Jira issues and Confluence pages, ensuring that changes in specifications automatically reflect in project tracking and documentation. Beyond simple sync, sddflow supports multi-host pull request automation, allowing AI agents to open, update, and merge code across multiple repositories or environments. Live progress dashboards provide real-time visibility into completion rates, blockers, and review status, empowering both human leads and autonomous agents to make informed decisions without leaving their preferred tools.
Getting started with sddflow involves a straightforward installation via pip, provided the host runs Python 3.10 or newer—a version chosen to leverage modern asyncio and type hinting capabilities. For existing projects, the tool includes a migration helper that upgrades legacy manifest.yml files to the current pack format, preserving custom configurations while adopting new schema improvements. This backward-compatible approach reduces friction for teams already experimenting with SDD. The migration wizard prompts users to review mapping differences, apply suggested changes, and validate the updated file against a built-in schema checker, ensuring that subsequent commands operate on a reliable foundation.
Before any synchronization occurs, sddflow validates connectivity to the configured Atlassian instances. A dedicated ping command queries Jira and Confluence endpoints using stored credentials, returning a succinct success or failure message that includes latency metrics and API version details. Output varies slightly depending on whether a single unified profile is used or separate profiles for Jira and Confluence on distinct servers. In dry-run mode, the tool simulates the ping without consuming API rate limits, displaying what would be sent and expected responses. This feature is invaluable for CI/CD pipelines where pre-flight checks prevent costly authentication failures mid-execution.
Prioritization often becomes a bottleneck when translating high-level feature ideas into actionable work items. sddflow addresses this by implementing a configurable MoSCoW (Must, Should, Could, Won’t) to Jira priority mapping defined in integrations.yml. Teams can tailor how each SDD priority level maps to Jira’s numeric priority fields, ensuring that critical features surface at the top of backlogs. After mapping, the CLI can pull the latest statuses of linked Jira issues and display them alongside task IDs directly in the terminal or dashboard view. This bidirectional sync keeps specification status and issue tracking in harmony, reducing the need for manual status updates and minimizing the risk of outdated information.
Documentation is another area where sddflow excels. The publish command takes generated SDD artifacts—such as feature specs, design decisions, and test plans—and creates or updates corresponding Confluence pages. Users can choose between creating new pages in a designated space or updating existing ones based on page ID or title patterns. A dry-run option renders the intended Confluence markup (in the platform’s storage format) without performing the actual API call, allowing reviewers to verify formatting, macro usage, and permission implications. This capability ensures that knowledge stays current, accessible, and aligned with the evolving codebase, a critical factor for onboarding and long-term maintainability.
Visibility into the health of specifications across the development lifecycle is facilitated by a dedicated review state command. It aggregates data from all phases—draft, review, approved, and deprecated—and presents a concise matrix showing how many documents reside in each state per feature. The output includes color-coded indicators (when supported by the terminal) and links to the underlying files, making it easy to spot stalled items or forgotten updates. Because the dashboard pulls live data from the filesystem and linked Atlassian services, it reflects the most recent commits and edits, providing a trustworthy basis for sprint planning and release gating.
Under the .specify/features/ directory, each feature folder contains a hierarchical set of specification files that sddflow interprets to generate Jira tickets and Confluence content. The tool distinguishes between two tiers of links: primary links that directly tie a spec file to its originating Jira issue or Confluence page, and secondary links that connect derived artifacts such as test plans or deployment notes. This tiered approach preserves traceability while accommodating the natural expansion of documentation as a feature matures. Users can navigate from a Jira issue back to the exact spec that inspired it, or from a Confluence diagram to the underlying design decision record, fostering a culture of accountability and reuse.
The operational model of sddflow is intentionally deterministic: each task triggers a single execution run, and re-running after applying fixes is discouraged unless the specification itself has changed. This prevents unnecessary churn and ensures that agents do not oscillate between states due to transient formatting differences. A key command, /address-review, remains available regardless of the pre_review setting, allowing developers or agents to respond to review comments, resolve conflicts, and mark items as ready for re-evaluation. By decoupling review handling from the main sync loop, the tool supports both synchronous and asynchronous workflows, accommodating teams that rely on scheduled batch processes as well as those favoring real-time collaboration.
Configuration is centralized in ~/.sdd/config.yml, where users define named authentication profiles—each capable of pointing to a different Atlassian instance, making it trivial to manage multiple Jira/Confluence ecosystems from a single workstation. API tokens are obtained via Atlassian’s security portal and stored securely in the operating system’s keychain, eliminating the need to embed secrets in environment variables or plain-text files. The absence of *_env fields reflects a deliberate security-first design: secrets are never exposed to child processes unless explicitly requested, reducing the attack surface. Profiles can be swapped via command-line flags or project-local overrides, enabling context-aware automation in monorepos or multi-product settings.
Beyond the core commands, sddflow exposes a suite of underlying utilities that can be invoked directly for advanced scripting. These include functions for rendering spec templates, validating YAML schemas, and generating changelogs from specification diffs. The integrations.yml.example file serves as a comprehensive reference, illustrating every supported mapping, webhook configuration, and extension point. The sdd init command auto-detects existing specification files in the current directory, scaffolds missing configuration, and proposes sensible defaults based on detected patterns. Licensed under the permissive MIT license, the project encourages community contributions, and its Python >=3.10 requirement ensures access to the latest language features and security updates.
Adopting sddflow offers tangible benefits for organizations seeking to scale AI-assisted development without sacrificing governance. Teams should begin by piloting the tool on a non-critical feature branch, using the dry-run capabilities to validate Jira/Confluence connectivity and spec-to-issue mapping. Metrics such as lead time from spec to PR, review cycle duration, and documentation freshness can be tracked before and after adoption to quantify impact. As AI coding agents become more prevalent, integrating them with structured specifications and robust project tooling will be essential for maintaining quality, compliance, and velocity. Embracing sddflow positions teams at the forefront of this evolution, turning autonomous coding from a experimental novelty into a repeatable, auditable process.