From ba6cc3e6a04e34ec7ea2127847ff24e75917ba16 Mon Sep 17 00:00:00 2001 From: Shayan Rais Date: Fri, 6 Mar 2026 12:56:26 +0500 Subject: [PATCH] updated docs --- .claude/rules/markdown-docs.md | 22 ++++++++++++++++++++++ .claude/rules/presentation.md | 13 +++++++++++++ .gitignore | 2 +- CLAUDE.md | 19 +++---------------- LICENSE | 21 +++++++++++++++++++++ README.md | 3 ++- 6 files changed, 62 insertions(+), 18 deletions(-) create mode 100644 .claude/rules/markdown-docs.md create mode 100644 .claude/rules/presentation.md create mode 100644 LICENSE diff --git a/.claude/rules/markdown-docs.md b/.claude/rules/markdown-docs.md new file mode 100644 index 0000000..f9ed288 --- /dev/null +++ b/.claude/rules/markdown-docs.md @@ -0,0 +1,22 @@ +# Glob: **/*.md + +## Documentation Standards + +- Keep files focused and concise — one topic per file +- Use relative links between docs (e.g., `../best-practice/claude-memory.md`), not absolute GitHub URLs +- Include back-navigation link at top of best-practice and report docs (see existing files for pattern) +- When adding a new concept or report, update the corresponding table in README.md (CONCEPTS or REPORTS) + +## Structure Conventions + +- Best practice docs go in `best-practice/` +- Implementation docs go in `implementation/` +- Reports go in `reports/` +- Tips go in `tips/` +- Changelog tracking goes in `changelog//` + +## Formatting + +- Use tables for structured comparisons (see README CONCEPTS table as reference) +- Use badge images from `!/tags/` for visual consistency when linking best-practice or implementation docs +- Keep headings hierarchical — don't skip levels (e.g., don't jump from `##` to `####`) diff --git a/.claude/rules/presentation.md b/.claude/rules/presentation.md new file mode 100644 index 0000000..689c38e --- /dev/null +++ b/.claude/rules/presentation.md @@ -0,0 +1,13 @@ +# Glob: presentation/** + +## Delegation Rule + +Any request to update, modify, or fix the presentation (`presentation/index.html`) MUST be handled by the `presentation-curator` agent. Always delegate presentation work to this agent via the Task tool — never edit the presentation directly. + +``` +Task(subagent_type="presentation-curator", description="...", prompt="...") +``` + +## Why + +The presentation-curator agent has three preloaded skills that keep it in sync with the presentation's structure, styling, and conceptual framework. It also self-evolves after every execution, updating its own skills to prevent knowledge drift. Bypassing the agent risks breaking slide numbering, level transitions, or style consistency. diff --git a/.gitignore b/.gitignore index 8b13789..42b5657 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1 @@ - +plan/ diff --git a/CLAUDE.md b/CLAUDE.md index a410bb1..d42a1f3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,12 +31,7 @@ Skills in `.claude/skills//SKILL.md` use YAML frontmatter: - `hooks`: Lifecycle hooks scoped to this skill ### Presentation System -Any request to update, modify, or fix the presentation (`presentation/index.html`) must be handled by the `presentation-curator` agent (`.claude/agents/presentation-curator.md`). Always delegate presentation work to this agent via the Task tool — never edit the presentation directly. - -The agent is **self-evolving**: after every execution, it updates its own skills to stay in sync with the presentation. It has three preloaded skills: -- `vibe-to-agentic-framework`: The conceptual framework ("Vibe Coding → Agentic Engineering"), weight rationale, and journey narrative. Updated after every slide change. -- `presentation-structure`: Slide format, weight system, navigation, section ranges. Updated when slides are added/removed/reordered. -- `presentation-styling`: CSS classes, component patterns, syntax highlighting. Updated when new styling patterns are introduced. +See `.claude/rules/presentation.md` — all presentation work is delegated to the `presentation-curator` agent. ### Hooks System Cross-platform sound notification system in `.claude/hooks/`: @@ -105,15 +100,7 @@ From experience with this repository: ## Documentation +See `.claude/rules/markdown-docs.md` for documentation standards. Key docs: - `docs/AGENTS.md`: Subagent orchestration troubleshooting -- `orchestration-workflow/orchestration-workflow.md`: Weather system flow diagram - `docs/COMPARISION.md`: Commands vs Agents vs Skills invocation patterns - -## Reports - -- `reports/claude-in-chrome-v-chrome-devtools-mcp.md`: Browser automation MCP comparison (Playwright vs Chrome DevTools vs Claude in Chrome) -- `best-practice/claude-memory.md`: CLAUDE.md loading behavior in monorepos (ancestor vs descendant loading) -- `reports/claude-skills-for-larger-mono-repos.md`: Skills discovery and loading behavior in monorepos (static vs dynamic discovery) -- `reports/claude-agent-memory.md`: Agent memory frontmatter — persistent memory scopes (user, project, local) for subagents -- `reports/claude-advanced-tool-use.md`: Advanced tool use patterns — Programmatic Tool Calling (PTC), Tool Search, Tool Use Examples -- `reports/claude-usage-and-rate-limits.md`: Usage commands (`/usage`, `/extra-usage`, `/cost`), rate limits, and pay-as-you-go overflow billing +- `orchestration-workflow/orchestration-workflow.md`: Weather system flow diagram diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..a618c28 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-2026 Shayan Rais + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index e1a1d47..3bfcfae 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,7 @@ claude - vanilla cc is better than any workflows with smaller tasks - use [skills in subfolders](reports/claude-skills-for-larger-mono-repos.md) for monorepos - use [/model](https://code.claude.com/docs/en/model-configuration) to select model and reasoning, [/context](https://code.claude.com/docs/en/context-management) to see context usage, [/usage](https://code.claude.com/docs/en/usage-billing) to set a weekly limit, [/config](https://code.claude.com/docs/en/settings) to configure settings -- always use [thinking mode](https://code.claude.com/docs/en/model-configuration) true (to see reasoning) and [Output Style](https://code.claude.com/docs/en/output-styles) Explanatory (to see detailed output with ★ Insight boxes) in /config for better understanding of Claude's decisions +- always use [thinking mode](https://code.claude.com/docs/en/model-configuration) true (to see reasoning) and [Output Style](https://code.claude.com/docs/en/output-styles) Explanatory (to see detailed output with ★ Insight boxes) in [/config](https://code.claude.com/docs/en/settings) for better understanding of Claude's decisions - use ultrathink keyword in prompts for [high effort reasoning](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#tips-and-best-practices) - [/rename](https://code.claude.com/docs/en/cli-reference) important sessions (e.g. [TODO - refactor task]) and [/resume](https://code.claude.com/docs/en/cli-reference) them later - use [Esc Esc or /rewind](https://code.claude.com/docs/en/checkpointing) to undo when Claude goes off-track instead of trying to fix it in the same context @@ -129,6 +129,7 @@ claude - use mcp ([Claude in Chrome](https://code.claude.com/docs/en/chrome), [Playwright](https://github.com/microsoft/playwright-mcp), [Chrome DevTools](https://developer.chrome.com/blog/chrome-devtools-mcp)) to let claude see chrome console logs on its own - always ask claude to run the terminal (you want to see logs of) as a background task for better debugging - [/doctor](https://code.claude.com/docs/en/cli-reference) to diagnose installation, authentication, and configuration issues +- error during compaction can be resolved by using [/model](https://code.claude.com/docs/en/model-configuration) to select a 1M token model, then running [/compact](https://code.claude.com/docs/en/context-management) - use a [cross-model](development-workflows/cross-model-workflow/cross-model-workflow.md) for QA — e.g. [Codex](https://github.com/shanraisshan/codex-cli-best-practice) for plan and implementation review ■ **Utilities (5)**