diff --git a/ORG_ARCHITECTURE.md b/ORG_ARCHITECTURE.md new file mode 100644 index 0000000..da12ce2 --- /dev/null +++ b/ORG_ARCHITECTURE.md @@ -0,0 +1,38 @@ +# Org Architecture: Documentation & Website Strategy + +Architecture decision record for the agent-sh organization's web presence and documentation. + +## Decisions + +### URL Structure + +| Site | URL | Purpose | +|------|-----|---------| +| Landing page | `agent-sh.github.io` (root) | Org overview, plugin catalog, skills directory | +| agentsys docs | `agent-sh.github.io/agentsys/` | Product docs for the agent runtime | +| agnix docs | `agent-sh.github.io/agnix/` | Product docs for the config linter | + +Custom domain (`agent-sh.dev`) is a future step - configure via GitHub Pages CNAME when ready. + +### Frameworks + +| Site | Framework | Reason | +|------|-----------|--------| +| Landing page | Astro 5 | Static-first, zero JS by default, component islands | +| agnix docs | Docusaurus 3 | WASM playground requires React, existing Docusaurus setup | +| agentsys docs | Upgrade from static HTML | Currently hand-written HTML, planned upgrade to Astro or Docusaurus | + +### Design Tokens + +`agent-sh.dev/src/styles/tokens.css` is the canonical source for design tokens (colors, spacing, typography). Other sites mirror these values to maintain visual consistency. + +### Documentation Hub + +The landing site includes a `/docs/` page that links to all documentation sites. This provides a single entry point for users looking for docs. + +## Future Work + +- **Unified search** - Orama or similar for cross-site search +- **Shared header/footer** - Web components or build-time includes for consistent navigation +- **Custom domain** - `agent-sh.dev` pointing to GitHub Pages +- **agentsys docs upgrade** - Migrate from static HTML to a framework with better DX diff --git a/README.md b/README.md index 1b7f5c3..59cea61 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,44 @@ -# Starlight Starter Kit: Basics +# agent-sh.dev -[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build) +Landing site for the agent-sh organization. Static Astro 5 site deployed to `agent-sh.github.io`. -``` -npm create astro@latest -- --template starlight -``` - -> πŸ§‘β€πŸš€ **Seasoned astronaut?** Delete this file. Have fun! - -## πŸš€ Project Structure - -Inside of your Astro + Starlight project, you'll see the following folders and files: +## Structure ``` . -β”œβ”€β”€ public/ -β”œβ”€β”€ src/ -β”‚ β”œβ”€β”€ assets/ -β”‚ β”œβ”€β”€ content/ -β”‚ β”‚ └── docs/ -β”‚ └── content.config.ts -β”œβ”€β”€ astro.config.mjs -β”œβ”€β”€ package.json -└── tsconfig.json +β”œβ”€β”€ ORG_ARCHITECTURE.md Architecture decision record +β”œβ”€β”€ astro.config.mjs Site config (base: /) +β”œβ”€β”€ public/ Static assets +└── src/ + β”œβ”€β”€ components/ + β”‚ β”œβ”€β”€ Nav.astro Top navigation with Products dropdown + β”‚ └── Footer.astro Site footer + β”œβ”€β”€ data/ + β”‚ β”œβ”€β”€ plugins.json Plugin catalog data + β”‚ └── skills.json Skills directory data + β”œβ”€β”€ layouts/ + β”‚ └── Base.astro Base HTML layout + β”œβ”€β”€ pages/ + β”‚ β”œβ”€β”€ index.astro Landing page - hero, stats, products, philosophy + β”‚ β”œβ”€β”€ docs.astro Documentation hub linking to all product docs + β”‚ β”œβ”€β”€ plugins.astro Plugin catalog with filters + β”‚ └── skills.astro Skills directory with search + └── styles/ + β”œβ”€β”€ tokens.css Design tokens (canonical source for all sites) + └── main.css Site styles ``` -Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name. - -Images can be added to `src/assets/` and embedded in Markdown with a relative link. - -Static assets, like favicons, can be placed in the `public/` directory. - -## 🧞 Commands +## Commands -All commands are run from the root of the project, from a terminal: +| Command | Action | +| :------------------ | :------------------------------------------ | +| `npm install` | Install dependencies | +| `npm run dev` | Start local dev server at localhost:4321 | +| `npm run build` | Build production site to ./dist/ | +| `npm run preview` | Preview build locally before deploying | -| Command | Action | -| :------------------------ | :----------------------------------------------- | -| `npm install` | Installs dependencies | -| `npm run dev` | Starts local dev server at `localhost:4321` | -| `npm run build` | Build your production site to `./dist/` | -| `npm run preview` | Preview your build locally, before deploying | -| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` | -| `npm run astro -- --help` | Get help using the Astro CLI | +## Deployment -## πŸ‘€ Want to learn more? +Deployed to GitHub Pages via `.github/workflows/deploy.yml`. Base path is `/`. -Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat). +See [ORG_ARCHITECTURE.md](./ORG_ARCHITECTURE.md) for the full architecture decision record covering URL structure, frameworks, design tokens, and future work. diff --git a/astro.config.mjs b/astro.config.mjs index ec60461..224c428 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -3,5 +3,5 @@ import { defineConfig } from 'astro/config'; export default defineConfig({ site: 'https://agent-sh.github.io', - base: '/agent-sh.dev/', + base: '/', }); diff --git a/src/components/Footer.astro b/src/components/Footer.astro index 427acf0..76bea35 100644 --- a/src/components/Footer.astro +++ b/src/components/Footer.astro @@ -10,21 +10,28 @@ const base = import.meta.env.BASE_URL;
Products - agentsys - agnix - web-ctl +
Resources - Plugin Catalog - Skills Directory - GitHub Org +
Community - Discussions - Issues - npm +
diff --git a/src/components/Nav.astro b/src/components/Nav.astro index 3721e37..35aacdc 100644 --- a/src/components/Nav.astro +++ b/src/components/Nav.astro @@ -30,12 +30,13 @@ function isActive(path: string) { agnix Agent config linter - + web-ctl - Browser automation (coming soon) + Browser automation
+ Docs Plugins Skills @@ -53,6 +54,7 @@ function isActive(path: string) { Home agentsys agnix + Docs Plugins Skills GitHub diff --git a/src/data/plugins.json b/src/data/plugins.json index e9fad77..e595744 100644 --- a/src/data/plugins.json +++ b/src/data/plugins.json @@ -3,7 +3,7 @@ "name": "next-task", "description": "Task to production. 12-phase pipeline: discovery, exploration, planning, implementation, review, and shipping.", "category": "workflow", - "agents": 8, + "agents": 10, "skills": 3, "commands": 1, "repo": "https://github.com/agent-sh/next-task", @@ -14,7 +14,7 @@ "name": "ship", "description": "Branch to merged PR in one command. Commits, pushes, creates PR, monitors CI, addresses reviewer comments, merges.", "category": "workflow", - "agents": 3, + "agents": 0, "skills": 1, "commands": 1, "repo": "https://github.com/agent-sh/ship", @@ -23,7 +23,7 @@ }, { "name": "agnix", - "description": "Lint agent configurations with 229 validation rules across 10+ AI tools. SARIF output for GitHub Code Scanning.", + "description": "Lint agent configurations with 230 validation rules across 10+ AI tools. SARIF output for GitHub Code Scanning.", "category": "quality", "agents": 1, "skills": 1, @@ -36,7 +36,7 @@ "name": "deslop", "description": "Kill AI slop before it ships. 3-phase detection pipeline finds debug statements, placeholder text, verbose comments.", "category": "quality", - "agents": 2, + "agents": 1, "skills": 1, "commands": 1, "repo": "https://github.com/agent-sh/deslop", @@ -45,10 +45,10 @@ }, { "name": "enhance", - "description": "Seven parallel analyzers check prompts, agents, plugins, docs, hooks, and skills. Certainty-graded findings.", + "description": "Eight parallel analyzers check prompts, agents, plugins, docs, hooks, skills, and cross-file consistency. Certainty-graded findings.", "category": "quality", - "agents": 7, - "skills": 8, + "agents": 8, + "skills": 9, "commands": 1, "repo": "https://github.com/agent-sh/enhance", "install": "agentsys install enhance", @@ -59,7 +59,7 @@ "description": "Evidence-backed performance investigation. 10-phase methodology with baselines, profiling, and controlled experiments.", "category": "research", "agents": 6, - "skills": 7, + "skills": 8, "commands": 1, "repo": "https://github.com/agent-sh/perf", "install": "agentsys install perf", @@ -78,7 +78,7 @@ }, { "name": "audit-project", - "description": "Multi-agent code review. Up to 10 specialized agents review security, performance, architecture, and more.", + "description": "Multi-agent code review. Up to 10 specialized role-based agents review security, performance, architecture, and more.", "category": "quality", "agents": 10, "skills": 1, @@ -131,16 +131,26 @@ "install": "agentsys install consult", "dependencies": [] }, + { + "name": "debate", + "description": "Structured multi-round AI debates. Proposer vs challenger with evidence-backed arguments and synthesis.", + "category": "research", + "agents": 1, + "skills": 1, + "commands": 1, + "repo": "https://github.com/agent-sh/debate", + "install": "agentsys install debate", + "dependencies": ["consult"] + }, { "name": "web-ctl", - "description": "Browser automation and web testing toolkit for AI agents. Coming soon.", + "description": "Browser automation and web testing toolkit for AI agents. Headless browser control, authentication, and page interaction.", "category": "infrastructure", - "agents": 0, - "skills": 0, - "commands": 0, + "agents": 1, + "skills": 2, + "commands": 1, "repo": "https://github.com/agent-sh/web-ctl", - "install": "", - "dependencies": [], - "comingSoon": true + "install": "agentsys install web-ctl", + "dependencies": [] } ] diff --git a/src/data/skills.json b/src/data/skills.json index 2210946..e30dbf0 100644 --- a/src/data/skills.json +++ b/src/data/skills.json @@ -2,17 +2,18 @@ { "name": "orchestrate-review", "plugin": "next-task", "description": "Multi-agent code review loop that iterates until clean", "platforms": ["Claude Code", "OpenCode", "Codex"] }, { "name": "discover-tasks", "plugin": "next-task", "description": "Scan GitHub Issues, GitLab, or local files for prioritized tasks", "platforms": ["Claude Code", "OpenCode", "Codex"] }, { "name": "validate-delivery", "plugin": "next-task", "description": "Pre-ship quality gate: tests, build, requirements check", "platforms": ["Claude Code", "OpenCode", "Codex"] }, - { "name": "enhance-agents", "plugin": "enhance", "description": "Analyze agent configuration quality and completeness", "platforms": ["Claude Code", "OpenCode", "Codex"] }, - { "name": "enhance-claudemd", "plugin": "enhance", "description": "Optimize CLAUDE.md project memory files", "platforms": ["Claude Code"] }, + { "name": "enhance-orchestrator", "plugin": "enhance", "description": "Coordinate all enhancement analyzers in parallel and produce a unified report", "platforms": ["Claude Code", "OpenCode", "Codex"] }, + { "name": "enhance-agent-prompts", "plugin": "enhance", "description": "Analyze agent prompts for prompt engineering best practices", "platforms": ["Claude Code", "OpenCode", "Codex"] }, + { "name": "enhance-claude-memory", "plugin": "enhance", "description": "Analyze and optimize CLAUDE.md or AGENTS.md project memory files", "platforms": ["Claude Code", "OpenCode", "Codex"] }, { "name": "enhance-docs", "plugin": "enhance", "description": "Documentation quality improvement analysis", "platforms": ["Claude Code", "OpenCode", "Codex"] }, { "name": "enhance-hooks", "plugin": "enhance", "description": "Git hooks and automation analysis", "platforms": ["Claude Code", "OpenCode", "Codex"] }, { "name": "enhance-plugins", "plugin": "enhance", "description": "Plugin configuration validation and optimization", "platforms": ["Claude Code", "OpenCode", "Codex"] }, { "name": "enhance-prompts", "plugin": "enhance", "description": "Prompt engineering best practices analysis", "platforms": ["Claude Code", "OpenCode", "Codex", "Cursor"] }, { "name": "enhance-skills", "plugin": "enhance", "description": "Skill definition quality and spec compliance", "platforms": ["Claude Code", "OpenCode", "Codex"] }, { "name": "enhance-cross-file", "plugin": "enhance", "description": "Cross-file semantic analysis for consistency", "platforms": ["Claude Code", "OpenCode", "Codex"] }, - { "name": "baseline", "plugin": "perf", "description": "Establish performance baselines before changes", "platforms": ["Claude Code", "OpenCode", "Codex"] }, - { "name": "benchmark", "plugin": "perf", "description": "Run controlled benchmarks with statistical analysis", "platforms": ["Claude Code", "OpenCode", "Codex"] }, - { "name": "profile", "plugin": "perf", "description": "CPU and memory profiling with flamegraph generation", "platforms": ["Claude Code", "OpenCode", "Codex"] }, + { "name": "perf-baseline-manager", "plugin": "perf", "description": "Manage performance baselines, consolidate results, and compare versions", "platforms": ["Claude Code", "OpenCode", "Codex"] }, + { "name": "perf-benchmarker", "plugin": "perf", "description": "Run sequential benchmarks with strict duration and warmup rules", "platforms": ["Claude Code", "OpenCode", "Codex"] }, + { "name": "perf-profiler", "plugin": "perf", "description": "CPU and memory profiling with flamegraph and hotspot evidence", "platforms": ["Claude Code", "OpenCode", "Codex"] }, { "name": "theory-tester", "plugin": "perf", "description": "Test performance hypotheses with controlled experiments", "platforms": ["Claude Code", "OpenCode", "Codex"] }, { "name": "code-paths", "plugin": "perf", "description": "Identify hot code paths and bottleneck functions", "platforms": ["Claude Code", "OpenCode", "Codex"] }, { "name": "theory-gatherer", "plugin": "perf", "description": "Generate performance hypotheses from profiling data", "platforms": ["Claude Code", "OpenCode", "Codex"] }, @@ -23,8 +24,12 @@ { "name": "repo-mapping", "plugin": "repo-map", "description": "Build AST-based symbol and import map of codebase", "platforms": ["Claude Code", "OpenCode", "Codex"] }, { "name": "sync-docs", "plugin": "sync-docs", "description": "Find and fix documentation drift from source code", "platforms": ["Claude Code", "OpenCode", "Codex"] }, { "name": "learn-topic", "plugin": "learn", "description": "Research topics online and create structured learning guides", "platforms": ["Claude Code", "OpenCode", "Codex"] }, - { "name": "agnix-lint", "plugin": "agnix", "description": "Validate agent configs with 229 rules across AI tools", "platforms": ["Claude Code", "OpenCode", "Codex", "Cursor"] }, + { "name": "agnix-lint", "plugin": "agnix", "description": "Validate agent configs with 230 rules across AI tools", "platforms": ["Claude Code", "OpenCode", "Codex", "Cursor"] }, { "name": "ship-pr", "plugin": "ship", "description": "Full PR lifecycle: create, monitor CI, address reviews, merge", "platforms": ["Claude Code", "OpenCode", "Codex"] }, { "name": "consult-tool", "plugin": "consult", "description": "Cross-tool AI consultation for second opinions", "platforms": ["Claude Code", "OpenCode", "Codex"] }, - { "name": "audit-review", "plugin": "audit-project", "description": "Multi-domain code review with specialized agents", "platforms": ["Claude Code", "OpenCode", "Codex"] } + { "name": "audit-review", "plugin": "audit-project", "description": "Multi-domain code review with specialized agents", "platforms": ["Claude Code", "OpenCode", "Codex"] }, + { "name": "debate", "plugin": "debate", "description": "Structured multi-round debates between AI tools with evidence-backed arguments", "platforms": ["Claude Code", "OpenCode", "Codex"] }, + + { "name": "web-auth", "plugin": "web-ctl", "description": "Authenticate to websites with human-in-the-loop browser handoff for login, 2FA, and CAPTCHAs", "platforms": ["Claude Code", "OpenCode", "Codex"] }, + { "name": "web-browse", "plugin": "web-ctl", "description": "Headless browser control for navigating and interacting with web pages", "platforms": ["Claude Code", "OpenCode", "Codex"] } ] diff --git a/src/pages/docs.astro b/src/pages/docs.astro new file mode 100644 index 0000000..87ac7e9 --- /dev/null +++ b/src/pages/docs.astro @@ -0,0 +1,111 @@ +--- +import Base from '../layouts/Base.astro'; +import Nav from '../components/Nav.astro'; +import Footer from '../components/Footer.astro'; +import '../styles/tokens.css'; +import '../styles/main.css'; +import pluginsData from '../data/plugins.json'; +import skillsData from '../data/skills.json'; + +const base = import.meta.env.BASE_URL; +const pluginCount = pluginsData.length; +const skillCount = skillsData.length; + +const docSites = [ + { + name: "agentsys", + description: "Agent runtime and orchestration system. Installation, plugin development, cross-platform compatibility, and API reference.", + url: "https://agent-sh.github.io/agentsys/", + badge: "Flagship", + badgeClass: "product-card__badge--flagship" + }, + { + name: "agnix", + description: "Agent config linter. Rule reference, SARIF integration, WASM playground, and custom rule development.", + url: "https://agent-sh.github.io/agnix/", + badge: "Tool", + badgeClass: "product-card__badge--tool" + }, + { + name: "web-ctl", + description: "Browser automation toolkit. Session management, authentication handoff, headless navigation, and selector reference.", + url: "https://github.com/agent-sh/web-ctl", + badge: "Tool", + badgeClass: "product-card__badge--tool" + } +]; + +const resources = [ + { name: "Plugin Catalog", description: `Browse all ${pluginCount} plugins with install commands`, url: `${base}plugins/` }, + { name: "Skills Directory", description: `${skillCount} skills across the ecosystem`, url: `${base}skills/` }, + { name: "GitHub Org", description: "Source code, issues, and discussions", url: "https://github.com/agent-sh" } +]; +--- + +