Skip to content

Commit 6bfb4b6

Browse files
nixrajputnixrajput
committed
chore: project scaffolding, AI/dev setup, and documentation
0 parents  commit 6bfb4b6

12 files changed

Lines changed: 640 additions & 0 deletions

‎.claude/settings.json‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
{
2+
"includeCoAuthoredBy": true,
3+
"permissions": {
4+
"allow": [
5+
"Edit",
6+
"Write",
7+
"NotebookEdit",
8+
"WebSearch",
9+
"WebFetch",
10+
"Bash(git status)",
11+
"Bash(git status *)",
12+
"Bash(git log)",
13+
"Bash(git log *)",
14+
"Bash(git diff)",
15+
"Bash(git diff *)",
16+
"Bash(git show)",
17+
"Bash(git show *)",
18+
"Bash(git rev-parse)",
19+
"Bash(git rev-parse *)",
20+
"Bash(git branch)",
21+
"Bash(git branch --list *)",
22+
"Bash(git branch -r)",
23+
"Bash(git branch -r *)",
24+
"Bash(git branch -a)",
25+
"Bash(git branch -v)",
26+
"Bash(git branch -vv)",
27+
"Bash(git remote)",
28+
"Bash(git remote -v)",
29+
"Bash(git remote show *)",
30+
"Bash(git stash list *)",
31+
"mcp__ide__*",
32+
"mcp__chrome-devtools__*",
33+
"mcp__claude-in-chrome__*",
34+
"mcp__playwright__*"
35+
],
36+
"deny": [
37+
"Read(./.env)",
38+
"Read(./.env.*)",
39+
"Read(./secrets/**)",
40+
"Read(./config/credentials.json)",
41+
"Read(./**/*.key)",
42+
"Read(./**/*.pem)",
43+
"Read(./**/*.crt)",
44+
"Write(./.env)",
45+
"Write(./.env.*)",
46+
"Write(./secrets/**)",
47+
"Write(./config/credentials.json)",
48+
"Write(./**/*.key)",
49+
"Write(./**/*.pem)",
50+
"Write(./**/*.crt)"
51+
],
52+
"ask": [
53+
"Bash(rm *)",
54+
"Bash(rmdir *)",
55+
"Bash(shred *)",
56+
"Bash(unlink *)",
57+
"Bash(dd *)",
58+
"Bash(mkfs *)",
59+
"Bash(fdisk *)",
60+
"Bash(chmod *)",
61+
"Bash(chown *)",
62+
"Bash(git commit *)",
63+
"Bash(git push *)",
64+
"Bash(git push --force *)",
65+
"Bash(git pull *)",
66+
"Bash(git merge *)",
67+
"Bash(git rebase *)",
68+
"Bash(git reset *)",
69+
"Bash(git checkout *)",
70+
"Bash(git switch *)",
71+
"Bash(git restore *)",
72+
"Bash(git clean *)",
73+
"Bash(git tag *)",
74+
"Bash(git fetch *)",
75+
"Bash(git stash *)",
76+
"Bash(git cherry-pick *)",
77+
"Bash(git am *)",
78+
"Bash(git apply *)",
79+
"Bash(git branch -d *)",
80+
"Bash(git branch -D *)",
81+
"Bash(git remote add *)",
82+
"Bash(git remote remove *)",
83+
"Bash(git remote set-url *)",
84+
"Bash(gh *)",
85+
"Bash(npm *)",
86+
"Bash(pip *)",
87+
"Bash(pip3 *)",
88+
"Bash(yarn *)",
89+
"Bash(pnpm *)",
90+
"Bash(docker *)",
91+
"Bash(kubectl *)",
92+
"Bash(firebase *)",
93+
"Bash(gcloud *)",
94+
"Bash(curl *)",
95+
"Bash(wget *)",
96+
"Bash(kill *)",
97+
"Bash(killall *)",
98+
"Bash(pkill *)"
99+
]
100+
},
101+
"enableAllProjectMcpServers": true,
102+
"enabledPlugins": {
103+
"ruby-lsp@claude-plugins-official": true,
104+
"shopify-plugin@shopify-ai-toolkit": true
105+
},
106+
"outputStyle": "Explanatory",
107+
"alwaysThinkingEnabled": false
108+
}

‎.gitignore‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Build artifacts
2+
/bin/
3+
/dist/
4+
*.tar.gz
5+
*.zip
6+
*.sha256
7+
8+
# Test artifacts
9+
coverage.out
10+
coverage.html
11+
12+
# Editor / IDE
13+
.vscode/
14+
.idea/
15+
*.swp
16+
*~
17+
18+
# OS
19+
.DS_Store
20+
Thumbs.db
21+
22+
# Local-only secrets and dumps
23+
*.local.sh
24+
.env
25+
.env.local
26+
/dumps/
27+
28+
# Logs
29+
*.log
30+
31+
# Superpowers brainstorming session artifacts
32+
.superpowers/
33+
34+
# Internal planning artifacts (specs, phase plans, brainstorming sessions)
35+
docs/superpowers/

‎.gitmessage‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Commit Message Template
2+
#
3+
# Conventional commit format (MUST FOLLOW EXACTLY):
4+
#
5+
# Single-line format:
6+
# <type>: <description>
7+
#
8+
# Multiline format:
9+
# <type>: summary
10+
#
11+
# - <description_line_1>.
12+
# - <description_line_2>.
13+
# - ...
14+
#
15+
# Field Definitions:
16+
# - <type>: One of "feat", "fix", "docs", "refactor", "test", "chore", "ci", "build", "perf"
17+
# - <description>: Generated commit message describing the changes
18+
# - <summary>: Generated summary of the changes including key points, impacted areas, and rationale (for multiline format)
19+
# - <description_line_X>: Message for a different concern in multiline format
20+
#
21+
# Types:
22+
# - feat: A new feature
23+
# - fix: A bug fix
24+
# - docs: Documentation changes
25+
# - refactor: Code refactoring
26+
# - test: Adding or updating tests
27+
# - chore: Maintenance tasks
28+
# - ci: Continuous integration changes
29+
# - build: Build system changes
30+
# - perf: Performance improvements
31+
#
32+
# Format Rules:
33+
# - Subject line <= 50 chars
34+
# - No trailing period in subject line
35+
# - Body lines wrapped at 72 chars
36+
# - Keep an empty line between summary and descriptions in multiline format
37+
# - Each bullet point MUST start with - (dash and space)
38+
# - Use present tense, imperative mood (e.g., "add feature" not "added feature")
39+
# - NEVER add extra content like "Generated with Claude Code", author info, etc.
40+
# - Post-review commits: Use multiline format with first bullet starting "Apply post-review fixes to <summary>"
41+
#
42+
# Examples:
43+
# feat: implement JWT-based login system
44+
# fix: fix memory leak in data processor
45+
# docs: update documentation for API endpoints
46+
#
47+
# Multiline example:
48+
# feat: implement dashboard analytics
49+
#
50+
# - Add user activity tracking components.
51+
# - Create data visualization charts.
52+
# - Integrate with reporting API.
53+
#
54+
# Post-review fixes example:
55+
# fix: fix memory leak in data processor
56+
#
57+
# - Apply post-review fixes to buffer management optimization.
58+
# - Update error handling for edge cases.
59+
# - Add missing null checks.

‎.mcp.json‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{
2+
"mcpServers": {
3+
"sequential-thinking": {
4+
"type": "stdio",
5+
"command": "npx",
6+
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
7+
},
8+
"memory": {
9+
"type": "stdio",
10+
"command": "npx",
11+
"args": ["-y", "@modelcontextprotocol/server-memory"]
12+
},
13+
"puppeteer": {
14+
"type": "stdio",
15+
"command": "npx",
16+
"args": ["-y", "@modelcontextprotocol/server-puppeteer"]
17+
},
18+
"playwright": {
19+
"type": "stdio",
20+
"command": "npx",
21+
"args": ["-y", "@playwright/mcp@latest"]
22+
},
23+
"chrome-devtools": {
24+
"type": "stdio",
25+
"command": "npx",
26+
"args": ["-y", "chrome-devtools-mcp@latest"]
27+
}
28+
}
29+
}

‎AGENTS.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# AI Agent Guidelines
2+
3+
Last updated: 2026-05-29
4+
5+
---
6+
7+
## Always-Active Instructions
8+
9+
> These apply to EVERY interaction, automatically.
10+
11+
### Working Discipline
12+
13+
> Behavioral guidelines to reduce common LLM coding mistakes. Bias toward caution over speed; for trivial tasks, use judgment.
14+
15+
#### 1. Think Before Coding
16+
17+
**Don't assume. Don't hide confusion. Surface tradeoffs.**
18+
19+
Before implementing:
20+
21+
- Read existing code and understand patterns before proposing changes.
22+
- State your assumptions explicitly. If uncertain, ask.
23+
- If multiple interpretations exist, present them — don't pick silently.
24+
- If a simpler approach exists, say so. Push back when warranted.
25+
- If something is unclear, stop. Name what's confusing. Ask.
26+
27+
#### 2. Simplicity First
28+
29+
**Minimum code that solves the problem. Nothing speculative.**
30+
31+
- No features beyond what was asked.
32+
- No abstractions for single-use code.
33+
- No "flexibility" or "configurability" that wasn't requested.
34+
- No error handling for impossible scenarios.
35+
- If you write 200 lines and it could be 50, rewrite it.
36+
37+
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
38+
39+
#### 3. Surgical Changes
40+
41+
**Touch only what you must. Clean up only your own mess.**
42+
43+
When editing existing code:
44+
45+
- Don't "improve" adjacent code, comments, or formatting.
46+
- Don't refactor things that aren't broken.
47+
- Match existing style, even if you'd do it differently.
48+
- If you notice unrelated dead code, mention it — don't delete it.
49+
50+
When your changes create orphans:
51+
52+
- Remove imports/variables/functions that YOUR changes made unused.
53+
- Don't remove pre-existing dead code unless asked.
54+
55+
The test: Every changed line should trace directly to the user's request.
56+
57+
#### 4. Goal-Driven Execution
58+
59+
**Define success criteria. Loop until verified.**
60+
61+
Transform tasks into verifiable goals:
62+
63+
- "Add validation" → "Write tests for invalid inputs, then make them pass"
64+
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
65+
- "Refactor X" → "Ensure tests pass before and after"
66+
67+
For multi-step tasks, state a brief plan:
68+
69+
```
70+
1. [Step] → verify: [check]
71+
2. [Step] → verify: [check]
72+
3. [Step] → verify: [check]
73+
```
74+
75+
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
76+
77+
#### 5. Report What Was Done
78+
79+
After completing work, state what changed and why — not just that it's done.
80+
81+
---
82+
83+
**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
84+
85+
### Multi-Agent Safety Rules
86+
87+
- **Never** create/apply/drop git stash entries unless explicitly requested
88+
- **Never** edit files in `node_modules/`, `vendor/`, or other dependency directories
89+
- **Always** work on a dedicated branch when running concurrent agents
90+
- **Never** force-push or rebase shared branches from an agent session
91+
- **Verify** no other agent is modifying the same files before making changes
92+
93+
---

‎CHANGELOG.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
12+
- Phase A skeleton: Go module, Cobra CLI with placeholder subcommands, Bubble Tea TUI placeholder, Driver interface + registry, errs package, config stub, Makefile, golangci-lint with depguard, CI workflow.

‎CLAUDE.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Claude Code Instructions
2+
3+
Read and follow all instructions in [AGENTS.md](AGENTS.md). This file ensures Claude Code auto-discovers the project guidelines.

‎CODE_OF_CONDUCT.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Code of Conduct
2+
3+
This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
4+
5+
By participating in this project you agree to abide by its terms.
6+
7+
Report violations to **conduct@siphon-project.org** (placeholder — update before public release).

‎CONTRIBUTING.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Contributing to siphon
2+
3+
Thanks for your interest. This project is in active early development; the design spec at `docs/superpowers/specs/2026-05-28-siphon-v1-design.md` is the source of truth.
4+
5+
## Development setup
6+
7+
```bash
8+
make tidy
9+
make test
10+
make lint
11+
make build
12+
```
13+
14+
## Layer rules (enforced by `golangci-lint`'s `depguard`)
15+
16+
- `cmd/` may only depend on `internal/cli`.
17+
- `internal/cli` and `internal/tui` are siblings; neither may import the other (except the root command, which launches the TUI on bare invocation).
18+
- `internal/cli` and `internal/tui` may only depend on `internal/app` (and shared `internal/errs`, `internal/config`).
19+
- `internal/app` may depend on `internal/driver`, `internal/config`, `internal/secrets`, `internal/dumps`, `internal/jobs`, `internal/errs`.
20+
- `internal/driver` packages may not import anything from `cli`, `tui`, or `app`.
21+
22+
Upward imports fail CI.
23+
24+
## Tests
25+
26+
- Unit tests: colocated `*_test.go`, run via `make test`.
27+
- Integration tests: behind `//go:build integration`, run via `make test-integration`.
28+
- TUI snapshot tests: under `internal/tui/testdata/` (Phase C onward).
29+
30+
## Commits
31+
32+
Follow Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `ci:`, `test:`, `refactor:`, `build:`).

0 commit comments

Comments
 (0)