npx skills add Amatofrancesco99/thoughtweave

Simplified Flow Diagram

What thoughtweave is

thoughtweave is a development workflow that puts understanding before generation. A collection of reusable skills that guide coding agents through specification, implementation, and documentation.

The workflow: Intent → Specification → Implementation → Explanation.

For the full philosophy, read IDEA.md. For the complete repository layout, read REPO_STRUCTURE.md.

Skills

/init-agents-file - Generate and maintain a project-specific AGENTS.md file that reflects the actual architecture, constraints, and conventions of your project. Built through a sequential interview - one question at a time, with branching logic based on repository state. Includes pre-condition checks, update mode, Claude compatibility, and output validation.
/sdd - The central skill. Transform ideas, Jira tickets, and feature requests into implementation-ready specifications. Never starts writing immediately - first assesses task complexity (light or deep mode), then asks three ordered questions, then assesses your competency per area, then enters a fluid Discovery phase. Includes Design TDD subskill for Given-When-Then test design. Mermaid diagrams integrated directly into specs.
/changes - Generate a human-readable explanation of implemented changes after coding. Documents why the change happened, what changed technically, runtime impact, tests performed, trade-offs accepted, and hidden assumptions discovered. Runs vulnerability scanning before generating output. Validates implementation maps back to spec requirements. For developers, reviewers, managers, and stakeholders.

What Makes It Different

thoughtweave shifts from spec → implement to intent → questioning → understanding → spec → implement.

Aspect	`spec-kit`	`superpowers`	`thoughtweave` (this repo)
Center	The specification	Process + TDD	The intent
Primary goal	Build high-quality software faster	Automate dev cycle autonomously	Understand the problem deeply
Starting point	`/speckit.specify`	Brainstorming	Intent discovery
Agent's role	SDD pipeline executor	Autonomous executor	Thinking partner and critic
Hidden assumptions	Assumptions section + markers	Not addressed	Mandatory - explicitly documented
AGENTS.md	Managed by extension	Static template	Built through conversational `/init-agents-file` interview
Specs lifecycle	Permanent per feature	Design docs → implemented	Permanent engineering memory
Post-implementation	Not addressed	Not addressed	Dedicated `/changes` skill
Learning support	Not addressed	Not addressed	Discovery phase built into `/sdd`
Skill count	11 + ecosystem	14	3
Maturity	Production	Production v6.0.3	v0.1.0

How to Use It

Define guidelines - Run /init-agents-file to set up repository standards (once per project).
Create a specification - Run /sdd to transform ideas into implementation-ready specs with test cases. If you use Jira, the agent can pull tickets directly - see the Jira integration setup below.

Requirements can be pulled directly from Jira via MCP. To enable this, configure the mcp-atlassian server in your editor or agent's MCP settings:
```
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}
```
Setup:
1. Create a Jira API token from https://id.atlassian.com/manage-profile/security/api-tokens.
2. Ensure the token has read access to the projects you want to pull tickets from.
3. Replace the placeholder values above with your Jira instance URL, email, and API token.
4. The agent will then be able to fetch tickets, browse projects, and use them as input for /sdd.
Implement - Start a new session. Implement based on the spec.
Document changes - Run /changes to document what changed, with vulnerability scanning.
Ship - Review, adjust, ship.

[!TIP] Each major phase should start a fresh coding-agent session to maintain context quality.

Start your preferred coding agent in web mode and use the slash commands (/init-agents-file, /sdd, /changes) as described in the workflow above. The skills are plain markdown - any agent can read and handle them.

Versioning & Release

Install via npx skills add Amatofrancesco99/thoughtweave.

[!CAUTION] Releases are created via GitHub Actions on push to main. The workflow in .github/workflows/release.yml accepts a workflow_dispatch input called version_bump with three options - major, minor, patch (default) - to control which semver component to increment. On push to main the workflow reads the latest git tag, increments the selected component, creates a new tag, and publishes a GitHub Release with auto-generated notes. If the latest commit already has a tag, the workflow skips to prevent duplicate releases.

Contributing

Contributions are welcome! See CONTRIBUTING.md for the full guide on branch strategy, PR workflow, local development setup, and how to use the skills to help you contribute.

[!IMPORTANT] Only repository owners can merge and approve pull requests to main. The default branch is protected by a server-side ruleset configured via Terraform (see terraform/). This ruleset blocks direct pushes, force pushes, and branch deletion - it cannot be bypassed locally with --no-verify.

License

MIT License. You are free to use, modify and distribute this repository. Attribution is truly appreciated.

Thoughtweave

README