Use this file to discover all available pages before exploring further.
Users can capture their intent, requirements, and design decisions in the form of specifications.AI agents reference them as needed when creating and implementing issues or other specifications.
Have a conversation with your AI agent about requirements, then capture the discussion in a spec.
1
Discuss requirements
> User: I want to improve our 'Open in IDE' button. Right now it just copiesthe worktree path to clipboard and users have to manually open their editor.Can we make it actually launch their IDE instead?I'm thinking:- Single click opens the worktree in their preferred editor- Support VS Code, Cursor, Windsurf, IntelliJ, Zed, Xcode, and custom commands- Users configure their preference locally (not in the repo)- Just local for now, no remote SSHHow would you approach this?⏺ Agent: I'll help you implement a proper "Open in IDE" feature that actuallylaunches the user's IDE. Let me start by exploring the current implementationto understand what we're working with.[Agent reviews existing code]Perfect! Now I have a good understanding. Let me present my approach:Approach for "Open in IDE" Feature:...
2
Refine iteratively
> User: Great! I want to note that users should set their preferenceglobally, and...[User can provide more feedback as necessary]⏺ Agent: Okay, I've noted this, would you like mte to createan implementation plan?
3
Capture in spec
> User: Alright, please create me a spec for this.⏺ Agent: I'll create a comprehensive specification for the "Open in IDE"feature with global user preferences.⏺ plugin:sudocode:sudocode - upsert_spec (MCP)(title: "Open in IDE -Global User Preference"...⏺ Perfect! I've created a comprehensive specification for the "Open in IDE" feature with global user preferences. Here's what I've documented:
Best for: New features where requirements need discussion and clarification.
Point to an existing spec and break a section into a more detailed subspecification.
1
Identify section to expand
> User: I've been looking at s-abc123 (OAuth Authentication System). Section 2.4on token refresh is pretty high-level. Can you break that down into a moredetailed subspecification?⏺ Agent: I'll review the parent spec and create a detailed subspecificationfor the token refresh section.⏺ plugin:sudocode:sudocode - show_spec (MCP)(spec_id: "s-abc123"...[Agent reviews the parent spec to understand context]
2
Agent creates child spec
⏺ Agent: I've reviewed the OAuth Authentication System spec. Let me createa detailed subspecification for the token refresh implementation.⏺ plugin:sudocode:sudocode - upsert_spec (MCP)(title: "OAuth Token RefreshImplementation", parent: "s-abc123"...⏺ Created s-def456: OAuth Token Refresh Implementation. I've documented:- Detection mechanisms for token expiration- Refresh request flow with token rotation- Error handling for various failure scenarios- Security considerations for refresh token storageThis subspecification is now linked to s-abc123 as a child spec.
3
Verify relationship
> User: Can you show me the parent spec to confirm it's linked?⏺ Agent: Sure, let me show you the parent spec.⏺ plugin:sudocode:sudocode - show_spec (MCP)(spec_id: "s-abc123"...⏺ The parent spec now shows s-def456 as a child specification undersection 2.4 Token Refresh.
Best for: Complex features with multiple subsystems that each need detailed specifications.
Ask the agent to research a topic and create a spec based on findings.
1
Request research
> User: Can you research OAuth 2.0 PKCE (Proof Key for Code Exchange) andcreate a spec based on your findings? I want to understand why we need itand how to implement it properly.⏺ Agent: I'll research PKCE for OAuth 2.0 and create a comprehensivespecification. Let me search for the official RFC and best practices.[Agent conducts web searches, reads RFCs, and reviews best practices]
2
Agent compiles findings
⏺ Agent: I've completed my research on PKCE. I found:- RFC 7636 defines the standard- PKCE prevents authorization code interception attacks- It's now recommended for all OAuth 2.0 flows, not just public clients- Implementation uses SHA256 code challenges with cryptographically random verifiersLet me create a spec documenting these findings.
3
Agent creates spec with sources
⏺ plugin:sudocode:sudocode - upsert_spec (MCP)(title: "PKCE for OAuth 2.0(RFC 7636)"...⏺ Created s-ghi789: PKCE for OAuth 2.0 (RFC 7636). I've documented:- What PKCE is and the problems it solves- Complete flow from code verifier generation through validation- Implementation requirements and security best practices- References to RFC 7636, OAuth 2.0 Security Best Practices, and OWASP guidelinesSince this relates to our OAuth Authentication System, I'll link it to s-abc123.⏺ plugin:sudocode:sudocode - link (MCP)(from_id: "s-ghi789", to_id: "s-abc123",type: "related"...⏺ The specs are now linked. You can reference s-ghi789 when implementingPKCE support in the authentication system.
Best for: Exploring new technologies, documenting industry standards, or researching best practices.
Use tags for categorization and filtering. Agents automatically add tags based on content, but you can also specify them explicitly when creating or updating specs.
Explain why this feature exists before describing what it does.Good:
## GoalsPrevent API abuse while supporting legitimate heavy usage.Free tier users need basic access, paid users need higher limits.## Requirements- Free tier: 100 requests/minute- Paid tier: 1000 requests/minute
Bad:
## RequirementsRate limiting with two tiers.
Separate Requirements from Implementation
Specs should describe what and why, not how.Requirements (spec):
Tokens must expire to limit damage from theft.Access tokens should be short-lived (minutes).Refresh tokens should enable re-authentication without credentials.
Implementation (code/issues):
Use JWT with RS256 signing.Access tokens expire in 15 minutes.Refresh tokens stored in Redis with 7-day TTL.
Expect Specs to Evolve
Specs are living documents. Agents will provide feedback:
## Token ExpirationTokens should expire appropriately.
Create implementation relationships between specs and issues using the implements relationship. Simply ask an agent to link an issue with a spec.Below is an example of what the agent will do:
