cokit-cli 1.2.6 → 1.3.0

package/templates/repo/.github/skills/frontend-development/resources/typescript-standards.md

@@ -0,0 +1,418 @@
+# TypeScript Standards
+
+TypeScript best practices for type safety and maintainability in React frontend code.
+
+---
+
+## Strict Mode
+
+### Configuration
+
+TypeScript strict mode is **enabled** in the project:
+
+```json
+// tsconfig.json
+{
+    "compilerOptions": {
+        "strict": true,
+        "noImplicitAny": true,
+        "strictNullChecks": true
+    }
+}
+```
+
+**This means:**
+- No implicit `any` types
+- Null/undefined must be handled explicitly
+- Type safety enforced
+
+---
+
+## No `any` Type
+
+### The Rule
+
+```typescript
+// ❌ NEVER use any
+function handleData(data: any) {
+    return data.something;
+}
+
+// ✅ Use specific types
+interface MyData {
+    something: string;
+}
+
+function handleData(data: MyData) {
+    return data.something;
+}
+
+// ✅ Or use unknown for truly unknown data
+function handleUnknown(data: unknown) {
+    if (typeof data === 'object' && data !== null && 'something' in data) {
+        return (data as MyData).something;
+    }
+}
+```
+
+**If you truly don't know the type:**
+- Use `unknown` (forces type checking)
+- Use type guards to narrow
+- Document why type is unknown
+
+---
+
+## Explicit Return Types
+
+### Function Return Types
+
+```typescript
+// ✅ CORRECT - Explicit return type
+function getUser(id: number): Promise<User> {
+    return apiClient.get(`/users/${id}`);
+}
+
+function calculateTotal(items: Item[]): number {
+    return items.reduce((sum, item) => sum + item.price, 0);
+}
+
+// ❌ AVOID - Implicit return type (less clear)
+function getUser(id: number) {
+    return apiClient.get(`/users/${id}`);
+}
+```
+
+### Component Return Types
+
+```typescript
+// React.FC already provides return type (ReactElement)
+export const MyComponent: React.FC<Props> = ({ prop }) => {
+    return <div>{prop}</div>;
+};
+
+// For custom hooks
+function useMyData(id: number): { data: Data; isLoading: boolean } {
+    const [data, setData] = useState<Data | null>(null);
+    const [isLoading, setIsLoading] = useState(true);
+
+    return { data: data!, isLoading };
+}
+```
+
+---
+
+## Type Imports
+
+### Use 'type' Keyword
+
+```typescript
+// ✅ CORRECT - Explicitly mark as type import
+import type { User } from '~types/user';
+import type { Post } from '~types/post';
+import type { SxProps, Theme } from '@mui/material';
+
+// ❌ AVOID - Mixed value and type imports
+import { User } from '~types/user';  // Unclear if type or value
+```
+
+**Benefits:**
+- Clearly separates types from values
+- Better tree-shaking
+- Prevents circular dependencies
+- TypeScript compiler optimization
+
+---
+
+## Component Prop Interfaces
+
+### Interface Pattern
+
+```typescript
+/**
+ * Props for MyComponent
+ */
+interface MyComponentProps {
+    /** The user ID to display */
+    userId: number;
+
+    /** Optional callback when action completes */
+    onComplete?: () => void;
+
+    /** Display mode for the component */
+    mode?: 'view' | 'edit';
+
+    /** Additional CSS classes */
+    className?: string;
+}
+
+export const MyComponent: React.FC<MyComponentProps> = ({
+    userId,
+    onComplete,
+    mode = 'view',  // Default value
+    className,
+}) => {
+    return <div>...</div>;
+};
+```
+
+**Key Points:**
+- Separate interface for props
+- JSDoc comments for each prop
+- Optional props use `?`
+- Provide defaults in destructuring
+
+### Props with Children
+
+```typescript
+interface ContainerProps {
+    children: React.ReactNode;
+    title: string;
+}
+
+// React.FC automatically includes children type, but be explicit
+export const Container: React.FC<ContainerProps> = ({ children, title }) => {
+    return (
+        <div>
+            <h2>{title}</h2>
+            {children}
+        </div>
+    );
+};
+```
+
+---
+
+## Utility Types
+
+### Partial<T>
+
+```typescript
+// Make all properties optional
+type UserUpdate = Partial<User>;
+
+function updateUser(id: number, updates: Partial<User>) {
+    // updates can have any subset of User properties
+}
+```
+
+### Pick<T, K>
+
+```typescript
+// Select specific properties
+type UserPreview = Pick<User, 'id' | 'name' | 'email'>;
+
+const preview: UserPreview = {
+    id: 1,
+    name: 'John',
+    email: 'john@example.com',
+    // Other User properties not allowed
+};
+```
+
+### Omit<T, K>
+
+```typescript
+// Exclude specific properties
+type UserWithoutPassword = Omit<User, 'password' | 'passwordHash'>;
+
+const publicUser: UserWithoutPassword = {
+    id: 1,
+    name: 'John',
+    email: 'john@example.com',
+    // password and passwordHash not allowed
+};
+```
+
+### Required<T>
+
+```typescript
+// Make all properties required
+type RequiredConfig = Required<Config>;  // All optional props become required
+```
+
+### Record<K, V>
+
+```typescript
+// Type-safe object/map
+const userMap: Record<string, User> = {
+    'user1': { id: 1, name: 'John' },
+    'user2': { id: 2, name: 'Jane' },
+};
+
+// For styles
+import type { SxProps, Theme } from '@mui/material';
+
+const styles: Record<string, SxProps<Theme>> = {
+    container: { p: 2 },
+    header: { mb: 1 },
+};
+```
+
+---
+
+## Type Guards
+
+### Basic Type Guards
+
+```typescript
+function isUser(data: unknown): data is User {
+    return (
+        typeof data === 'object' &&
+        data !== null &&
+        'id' in data &&
+        'name' in data
+    );
+}
+
+// Usage
+if (isUser(response)) {
+    console.log(response.name);  // TypeScript knows it's User
+}
+```
+
+### Discriminated Unions
+
+```typescript
+type LoadingState =
+    | { status: 'idle' }
+    | { status: 'loading' }
+    | { status: 'success'; data: Data }
+    | { status: 'error'; error: Error };
+
+function Component({ state }: { state: LoadingState }) {
+    // TypeScript narrows type based on status
+    if (state.status === 'success') {
+        return <Display data={state.data} />;  // data available here
+    }
+
+    if (state.status === 'error') {
+        return <Error error={state.error} />;  // error available here
+    }
+
+    return <Loading />;
+}
+```
+
+---
+
+## Generic Types
+
+### Generic Functions
+
+```typescript
+function getById<T>(items: T[], id: number): T | undefined {
+    return items.find(item => (item as any).id === id);
+}
+
+// Usage with type inference
+const users: User[] = [...];
+const user = getById(users, 123);  // Type: User | undefined
+```
+
+### Generic Components
+
+```typescript
+interface ListProps<T> {
+    items: T[];
+    renderItem: (item: T) => React.ReactNode;
+}
+
+export function List<T>({ items, renderItem }: ListProps<T>): React.ReactElement {
+    return (
+        <div>
+            {items.map((item, index) => (
+                <div key={index}>{renderItem(item)}</div>
+            ))}
+        </div>
+    );
+}
+
+// Usage
+<List<User>
+    items={users}
+    renderItem={(user) => <UserCard user={user} />}
+/>
+```
+
+---
+
+## Type Assertions (Use Sparingly)
+
+### When to Use
+
+```typescript
+// ✅ OK - When you know more than TypeScript
+const element = document.getElementById('my-element') as HTMLInputElement;
+const value = element.value;
+
+// ✅ OK - API response that you've validated
+const response = await api.getData();
+const user = response.data as User;  // You know the shape
+```
+
+### When NOT to Use
+
+```typescript
+// ❌ AVOID - Circumventing type safety
+const data = getData() as any;  // WRONG - defeats TypeScript
+
+// ❌ AVOID - Unsafe assertion
+const value = unknownValue as string;  // Might not actually be string
+```
+
+---
+
+## Null/Undefined Handling
+
+### Optional Chaining
+
+```typescript
+// ✅ CORRECT
+const name = user?.profile?.name;
+
+// Equivalent to:
+const name = user && user.profile && user.profile.name;
+```
+
+### Nullish Coalescing
+
+```typescript
+// ✅ CORRECT
+const displayName = user?.name ?? 'Anonymous';
+
+// Only uses default if null or undefined
+// (Different from || which triggers on '', 0, false)
+```
+
+### Non-Null Assertion (Use Carefully)
+
+```typescript
+// ✅ OK - When you're certain value exists
+const data = queryClient.getQueryData<Data>(['data'])!;
+
+// ⚠️ CAREFUL - Only use when you KNOW it's not null
+// Better to check explicitly:
+const data = queryClient.getQueryData<Data>(['data']);
+if (data) {
+    // Use data
+}
+```
+
+---
+
+## Summary
+
+**TypeScript Checklist:**
+- ✅ Strict mode enabled
+- ✅ No `any` type (use `unknown` if needed)
+- ✅ Explicit return types on functions
+- ✅ Use `import type` for type imports
+- ✅ JSDoc comments on prop interfaces
+- ✅ Utility types (Partial, Pick, Omit, Required, Record)
+- ✅ Type guards for narrowing
+- ✅ Optional chaining and nullish coalescing
+- ❌ Avoid type assertions unless necessary
+
+**See Also:**
+- [component-patterns.md](component-patterns.md) - Component typing
+- [data-fetching.md](data-fetching.md) - API typing

package/templates/repo/.github/skills/git/SKILL.md

@@ -1,17 +1,31 @@
 ---
 name: git
-description: Git operations with conventional commits. Use for staging, committing, pushing, PRs, merges. Auto-splits commits by type/scope. Security scans for secrets.
+description: "Git operations with conventional commits. Use for staging, committing, pushing, PRs, merges. Auto-splits commits by type/scope. Security scans for secrets."
+argument-hint: "cm|cp|pr|merge [args]"
 ---
 
 # Git Operations
 
-Execute git workflows via `git-manager` agent to isolate verbose output.
+## Default (No Arguments)
+
+If invoked without arguments, ask the user to present available git operations:
+
+| Operation | Description |
+|-----------|-------------|
+| `cm` | Stage files & create commits |
+| `cp` | Stage files, create commits and push |
+| `pr` | Create Pull Request |
+| `merge` | Merge branches |
+
+Present as options by asking the user with header "Git Operation", question "What would you like to do?".
+
+Execute git workflows via `git-manager` subagent to isolate verbose output.
 Activate `context-engineering` skill.
 
 **IMPORTANT:**
 - Sacrifice grammar for the sake of concision.
 - Ensure token efficiency while maintaining high quality.
-- Pass these rules to agents.
+- Pass these rules to subagents.
 
 ## Arguments
 - `cm`: Stage files & create commits
@@ -54,7 +68,7 @@ git diff --cached | grep -iE "(api[_-]?key|token|password|secret|credential)"
 
 **NOTE:**
 - Search for related issues on GitHub and add to body.
-- Only use `feat`, `fix`, or `perf` prefixes for files in `.copilot` directory (do not use `docs`).
+- Only use `feat`, `fix`, or `perf` prefixes for files in skills directory (do not use `docs`).
 
 **Split commits if:**
 - Different types mixed (feat + fix, code + docs)

package/templates/repo/.github/skills/git/references/commit-standards.md

@@ -23,7 +23,7 @@ type(scope): description
 - **No period at end**
 - **Scope optional but recommended**
 - **Focus on WHAT, not HOW**
-- Only use `feat`, `fix`, or `perf` prefixes for files in `.copilot` directory (do not use `docs`).
+- Only use `feat`, `fix`, or `perf` prefixes for files in skills directory (do not use `docs`).
 
 ## NEVER Include AI Attribution
 - ❌ "Generated with AI"
@@ -42,5 +42,5 @@ type(scope): description
 - ❌ `Fix bug` (not specific)
 
 ## Special Cases
-- `$HOME/.copilot/` skill updates: `perf(skill): improve token efficiency`
-- `$HOME/.copilot/` new skills: `feat(skill): add database-optimizer`
+- skill updates: `perf(skill): improve token efficiency`
+- new skills: `feat(skill): add database-optimizer`

package/templates/repo/.github/skills/git/references/workflow-commit.md

@@ -1,6 +1,6 @@
 # Commit Workflow
 
-Execute via `git-manager` agent.
+Execute via `git-manager` subagent.
 
 ## Tool 1: Stage + Analyze
 ```bash
@@ -12,7 +12,7 @@ echo "=== GROUPS ===" && \
 git diff --cached --name-only | awk -F'/' '{
   if ($0 ~ /\.(md|txt)$/) print "docs:"$0
   else if ($0 ~ /test|spec/) print "test:"$0
-  else if ($0 ~ /\.copilot/) print "config:"$0
+  else if ($0 ~ /skills|agents/) print "config:"$0
   else if ($0 ~ /package\.json|lock/) print "deps:"$0
   else print "code:"$0
 }'
@@ -24,7 +24,7 @@ git diff --cached --name-only | awk -F'/' '{
 
 NOTE: 
 - Search for related issues on GitHub and add to body.
-- Only use `feat`, `fix`, or `perf` prefixes for files in `.copilot` directory (do not use `docs`).
+- Only use `feat`, `fix`, or `perf` prefixes for files in skills directory (do not use `docs`).
 
 **From groups, decide:**
 

package/templates/repo/.github/skills/git/references/workflow-merge.md

@@ -1,6 +1,6 @@
 # Merge Workflow
 
-Execute via `git-manager` agent.
+Execute via `git-manager` subagent.
 
 ## Variables
 - TO_BRANCH: target (defaults to `main`)

package/templates/repo/.github/skills/git/references/workflow-pr.md

@@ -1,6 +1,6 @@
 # Pull Request Workflow
 
-Execute via `git-manager` agent.
+Execute via `git-manager` subagent.
 
 ## Variables
 - TO_BRANCH: target (defaults to `main`)

package/templates/repo/.github/skills/git/references/workflow-push.md

@@ -1,6 +1,6 @@
 # Push Workflow
 
-Execute via `git-manager` agent.
+Execute via `git-manager` subagent.
 
 ## Pre-Push Checklist
 1. All changes committed

package/templates/repo/.github/skills/mcp-management/README.md

@@ -4,7 +4,7 @@ Intelligent management and execution of Model Context Protocol (MCP) servers.
 
 ## Overview
 
-This skill enables the agent to discover, analyze, and execute MCP server capabilities without polluting the main context window. Perfect for context-efficient MCP integration using agent-based architecture.
+This skill enables Copilot to discover, analyze, and execute MCP server capabilities without polluting the main context window. Perfect for context-efficient MCP integration using subagent-based architecture.
 
 ## Features
 
@@ -12,20 +12,20 @@ This skill enables the agent to discover, analyze, and execute MCP server capabi
 - **Intelligent Tool Discovery**: Analyze which tools are relevant for specific tasks
 - **Progressive Disclosure**: Load only necessary tool definitions
 - **Execution Engine**: Call MCP tools with proper parameter handling
-- **Context Efficiency**: Delegate MCP operations to `mcp-manager` agent
+- **Context Efficiency**: Delegate MCP operations to `mcp-manager` subagent
 
 ## Quick Start
 
 ### 1. Install Dependencies
 
 ```bash
-cd $HOME/.copilot/skills/mcp-management/scripts
+cd skills/mcp-management/scripts
 npm install
 ```
 
 ### 2. Configure MCP Servers
 
-Create `$HOME/.copilot/.mcp.json`:
+Create `.vscode/mcp.json`:
 
 ```json
 {
@@ -42,12 +42,12 @@ Create `$HOME/.copilot/.mcp.json`:
 }
 ```
 
-See `$HOME/.copilot/.mcp.json.example` for more examples.
+See `.vscode/mcp.json.example` for more examples.
 
 ### 3. Test Connection
 
 ```bash
-cd $HOME/.copilot/skills/mcp-management/scripts
+cd skills/mcp-management/scripts
 npx ts-node cli.ts list-tools
 ```
 
@@ -71,13 +71,13 @@ The LLM reads `assets/tools.json` and intelligently selects tools. No separate a
 npx ts-node scripts/cli.ts call-tool memory add '{"key":"name","value":"Alice"}'
 ```
 
-### Pattern 4: Use with Agent
+### Pattern 4: Use with Subagent
 
-In main conversation:
+In main Copilot conversation:
 
 ```
 User: "I need to search the web and save results"
-Main Agent: [Spawns mcp-manager agent]
+Main Agent: [Spawns mcp-manager subagent]
 mcp-manager: Discovers brave-search + memory tools, reports back
 Main Agent: Uses recommended tools for implementation
 ```
@@ -85,9 +85,9 @@ Main Agent: Uses recommended tools for implementation
 ## Architecture
 
 ```
-Main Agent
+Main Agent (Copilot)
     ↓ (delegates MCP tasks)
-mcp-manager Agent
+mcp-manager Subagent
     ↓ (uses skill)
 mcp-management Skill
     ↓ (connects via)
@@ -96,7 +96,7 @@ MCP Servers (memory, filesystem, etc.)
 
 **Benefits**:
 - Main agent context stays clean
-- MCP discovery happens in isolated agent context
+- MCP discovery happens in isolated subagent context
 - Only relevant tool definitions loaded when needed
 - Reduced token usage
 
@@ -123,7 +123,7 @@ mcp-management/
 ### mcp-client.ts
 
 Core client manager class:
-- Load config from `$HOME/.copilot/.mcp.json`
+- Load config from `.vscode/mcp.json`
 - Connect to multiple MCP servers
 - List/execute tools, prompts, resources
 - Lifecycle management
@@ -145,9 +145,9 @@ Command-line interface:
 Scripts check for variables in this order:
 
 1. `process.env` (runtime)
-2. `$HOME/.copilot/skills/mcp-management/.env`
-3. `$HOME/.copilot/skills/.env`
-4. `$HOME/.copilot/.env`
+2. `skills/mcp-management/.env`
+3. `skills/.env`
+4. `.env`
 
 ### MCP Config Format
 
@@ -178,7 +178,7 @@ Install with `npx`:
 
 ## Integration with mcp-manager Agent
 
-The `mcp-manager` agent (`$HOME/.copilot/agents/mcp-manager.md`) uses this skill to:
+The `mcp-manager` agent (`agents/mcp-manager.agent.md`) uses this skill to:
 
 1. **Discover**: Connect to MCP servers, list capabilities
 2. **Analyze**: Filter relevant tools for tasks
@@ -191,7 +191,7 @@ This architecture keeps main context clean and enables efficient MCP integration
 
 ### "Config not found"
 
-Ensure `$HOME/.copilot/.mcp.json` exists and is valid JSON.
+Ensure `.vscode/mcp.json` exists and is valid JSON.
 
 ### "Server connection failed"