# Command: {command-name}

> **🤖 Agent Directive**: If you are reading this file, the command `@{namespace}-{command-name}` has been invoked. Follow the steps below to execute this command.

**Namespace**: {namespace}
**Version**: 1.0.0
**Created**: YYYY-MM-DD
**Last Updated**: YYYY-MM-DD
**Status**: [Draft | Active | Deprecated]

---

**Purpose**: [One-line description of what this command does]
**Category**: [Workflow | Documentation | Maintenance | Creation | Custom]
**Frequency**: [Once | Per Session | As Needed | Continuous]

---

## What This Command Does

[2-3 paragraph explanation of:
- What the command accomplishes
- When to use it
- What problems it solves
- Any important context]

**Example**: "This command initializes the agent context by reading all documentation in the agent/ directory, reviewing key source files, and updating progress tracking. Use this at the start of each session to ensure the agent has complete project context."

---

## Prerequisites

[List any requirements before running this command:]

- [ ] Prerequisite 1 (e.g., "Docker must be installed")
- [ ] Prerequisite 2 (e.g., "AWS credentials configured")
- [ ] Prerequisite 3 (e.g., "Build completed successfully")

**Example** (for a deployment command):
- [ ] Docker installed and running
- [ ] AWS CLI configured with valid credentials
- [ ] Application built successfully (`npm run build` completed)
- [ ] Environment variables configured in `.env.production`

---

## Steps

[Detailed, sequential steps the agent should follow:]

### 1. [Step Name]

[Description of what to do in this step]

**Actions**:
- Action item 1
- Action item 2
- Action item 3

**Expected Outcome**: [What should happen after this step]

**Example**:
```bash
# If shell commands needed
command --with-flags
```

```typescript
// If code examples needed
const example = "code";
```

### 2. [Next Step]

[Description of what to do]

**Actions**:
- Action item 1
- Action item 2

**Expected Outcome**: [What should happen]

### 3. [Next Step]

[Continue with additional steps as needed]

---

## Verification

[Checklist to confirm command executed successfully:]

- [ ] Verification item 1: [Specific condition to check]
- [ ] Verification item 2: [Specific condition to check]
- [ ] Verification item 3: [Specific condition to check]
- [ ] Verification item 4: [Specific condition to check]

**Example**:
- [ ] All agent files read successfully
- [ ] Key source files identified and reviewed
- [ ] `agent/progress.yaml` updated with current status
- [ ] No errors encountered during execution

---

## Expected Output

[Describe what the user should see after command execution:]

### Files Modified
- `path/to/file1` - [What changed]
- `path/to/file2` - [What changed]

### Console Output
```
Example output message or status report
```

### Status Update
[Description of any status changes in progress.yaml or other tracking]

**Example**:

### Files Modified
- `agent/progress.yaml` - Updated current status and recent work

### Console Output
```
✓ Read 15 agent files
✓ Reviewed 8 source files
✓ Updated progress tracking
✓ Ready to proceed with task-3
```

### Status Update
- Current milestone: M1 (Foundation)
- Current task: task-3 (Implement core logic)
- Progress: 40% complete

---

## Examples

### Example 1: [Scenario Name]

**Context**: [When you'd use this command in this way]

**Invocation**: `@{namespace}-{command-name}`

**Result**: [What happens]

**Example**:

### Example 1: Starting Fresh Session

**Context**: Beginning work on a project after a break

**Invocation**: `@acp-init`

**Result**: Agent reads all documentation, reviews source code, updates progress tracking, and reports current status with next steps.

### Example 2: [Another Scenario]

**Context**: [Different use case]

**Invocation**: `@{namespace}-{command-name}`

**Result**: [What happens]

---

## Related Commands

[Link to related commands and explain relationships:]

- [`@{namespace}-{related-command}`](../{namespace}/{related-command}.md) - [When to use instead or in combination]
- [`@{namespace}-{another-command}`](../{namespace}/{another-command}.md) - [How it relates]

**Example**:
- [`@acp-proceed`](../acp/proceed.md) - Use after `@acp-init` to start working on tasks
- [`@acp-status`](../acp/status.md) - Use to check current status without full initialization
- [`@acp-sync`](../acp/sync.md) - Use to update documentation after code changes

---

## Troubleshooting

### Issue 1: [Common Problem]

**Symptom**: [What the user sees]

**Cause**: [Why this happens]

**Solution**: [How to fix it]

**Example** (for a deployment command):

### Issue 1: Deployment fails with authentication error

**Symptom**: Error message "AWS credentials not found"

**Cause**: AWS CLI not configured or credentials expired

**Solution**: Run `aws configure` to set up credentials, or refresh your AWS SSO session with `aws sso login`

### Issue 2: [Another Common Problem]

**Symptom**: [What the user sees]

**Cause**: [Why this happens]

**Solution**: [How to fix it]

---

## Security Considerations

[Document any security implications of this command:]

### File Access
- **Reads**: [What files this command reads]
- **Writes**: [What files this command modifies]
- **Executes**: [Any scripts or commands this executes]

### Network Access
- **APIs**: [Any external APIs called]
- **Repositories**: [Any git operations]

### Sensitive Data
- **Secrets**: [How this command handles secrets - should never read them]
- **Credentials**: [How this command handles credentials]

**Example**:

### File Access
- **Reads**: All files in `agent/` directory, key source files in `src/`
- **Writes**: `agent/progress.yaml` only
- **Executes**: None

### Network Access
- **APIs**: None
- **Repositories**: None

### Sensitive Data
- **Secrets**: Never reads `.env` files or credential files
- **Credentials**: Does not access any credentials

---

## Notes

[Any additional context, warnings, or considerations:]

- Note 1: [Important information]
- Note 2: [Important information]
- Note 3: [Important information]

**Example**:
- This command should be run at the start of each session
- Reading all agent files may take 30-60 seconds for large projects
- If source code is very large, consider specifying which files to review
- Always review the output to ensure context was loaded correctly

---

**Namespace**: {namespace}
**Command**: {command-name}
**Version**: 1.0.0
**Created**: YYYY-MM-DD
**Last Updated**: YYYY-MM-DD
**Status**: [Draft | Active | Deprecated]
**Compatibility**: ACP 1.1.0+
**Author**: [Your name or organization]